Implement suspend() and resume() for OfflineAudioContext

Source/modules/webaudio/OfflineAudioContext.h

 /*
  * Copyright (C) 2012, Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1.  Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2.  Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
@@ skipping 10 matching lines @@
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef OfflineAudioContext_h
 #define OfflineAudioContext_h
 
 #include "modules/ModulesExport.h"
 #include "modules/webaudio/AbstractAudioContext.h"
 
+#include "wtf/HashMap.h"
+
 namespace blink {
 
 class ExceptionState;
+class ScheduledSuspendContainer;
+class OfflineAudioDestinationHandler;
+
+// The HashMap with 'zero' key is needed because |currentSampleFrame| can be
+// zero. Also ScheduledSuspendContainer is a raw pointer (rather than RefPtr)
+// because it must be guaranteed that the main thread keeps it alive while the

[Raymond Toy, 2015/07/15 20:59:14]

What does "must be guaranteed that the main thread keeps it alive..." mean?  Is
it because a RefPtr would allow the main thread to delete it while the audio
thread still wants it?  Would the solution to this be to call ref() on it on
creation so that there's another reference to it and deref it when the audio
thread is done with it?

[hongchan, 2015/07/15 23:24:22]

Conceptually, I believe it is cleaner to separate the role here; the main thread
is the provider and the render thread is the user of SuspendContainer object.
Based on the review from haraken@ and hiroshige@, I believe this is safe in
terms of the cross-thread operation.

If you have a better idea/design, I am open to that as well.

[Raymond Toy, 2015/07/16 16:52:04]

Acknowledged.

+// render thread uses it.
+using SuspendContainerMap = HashMap<size_t, ScheduledSuspendContainer*, DefaultHash<size_t>::Hash, WTF::UnsignedWithZeroKeyHashTraits<size_t>>;
 
 class MODULES_EXPORT OfflineAudioContext final : public AbstractAudioContext {
     DEFINE_WRAPPERTYPEINFO();
 public:
     static OfflineAudioContext* create(ExecutionContext*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate, ExceptionState&);
 
     ~OfflineAudioContext() override;
 
+    DECLARE_VIRTUAL_TRACE();
+
+    DEFINE_ATTRIBUTE_EVENT_LISTENER(complete);
+
+    // Check all the scheduled suspends if the context should suspend at
+    // currentTime(). Then post tasks to resolve promises on the main thread
+    // if necessary.
+    bool shouldSuspendNow();
+
+    // Clear suspensions marked as 'resolved' in the list.
+    void resolvePendingSuspendPromises();
+
+    // Fire completion event when the rendering is finished.
+    void fireCompletionEvent();
+
     ScriptPromise startOfflineRendering(ScriptState*);
 
     ScriptPromise closeContext(ScriptState*) final;
+    ScriptPromise suspendContext(ScriptState*, double) final;
+    ScriptPromise resumeContext(ScriptState*) final;
+
+    // This is to implement the pure virtual method from AbstractAudioContext.
+    // CANNOT be called on OfflineAudioContext.
     ScriptPromise suspendContext(ScriptState*) final;
-    ScriptPromise resumeContext(ScriptState*) final;
 
     bool hasRealtimeConstraint() final { return false; }
 
 private:
     OfflineAudioContext(Document*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate);
+
+    // Fetch directly the destination handler.
+    OfflineAudioDestinationHandler& destinationHandler();
+
+    // Check a suspend container if it has a duplicate scheduled frame or
+    // is behind the current frame. If the validation fails, post a task to the
+    // main thread to reject the promise.
+    void validateSuspendContainerOnRenderThread(ScheduledSuspendContainer*);
+
+    // Reject a suspend container on the main thread when the validation fails.
+    void rejectSuspendContainerOnMainThread(ScheduledSuspendContainer*);
+
+    // Resolve a pending suspend container.
+    void resolveSuspendContainerOnMainThread(ScheduledSuspendContainer*);
+
+    SuspendContainerMap m_scheduledSuspends;
+    RefPtrWillBeMember<ScriptPromiseResolver> m_completeResolver;
+
+    // This flag is necessary to indicate the rendering has actually started.
+    // Note that initial state of context is 'Suspended', which is the same
+    // state when the context is suspended.
+    bool m_isRenderingStarted;
+
+    // Total render sample length.
+    size_t m_totalRenderFrames;
+};
+
+// A container class for a pair of time information and the suspend promise
+// resolver. This class does not need to be |ThreadSafeRefCounted| because it
+// needs to be created and destructed in the same thread.

[Raymond Toy, 2015/07/15 20:59:14]

"same thread" as what?  And why does it need to be created and destroyed in the
same thread?

[hongchan, 2015/07/15 23:24:22]

This object is created and destroyed in the main thread.

This design is suggested by haraken@; if we can constrain the object to be
created/destroyed in the same thread, we do not need  |ThreadSafeRefCounted|. I
think it is cleaner that way and also easier to apply oilpan in the future.

[Raymond Toy, 2015/07/16 16:24:23]

Just change the comment from "same thread" to "main thread".  It wasn't clear
whether it was audio thread, offline thread, main thread or some possible mix of
all as long as the creation/destruction was in the same thread.

+class ScheduledSuspendContainer {
+public:
+    static ScheduledSuspendContainer* create(double suspendTime, size_t suspendFrame, PassRefPtrWillBeRawPtr<ScriptPromiseResolver>);
+    ~ScheduledSuspendContainer();
+
+    double suspendTime() const { return m_suspendTime; }
+    size_t suspendFrame() const { return m_suspendFrame; }
+
+    // Set the error message for the reason of rejection on the render thread
+    // before sending it to the main thread.
+    void setErrorMessageForRejection(ExceptionCode, const String&);
+
+    // {Resolve, Reject} the promise resolver on the main thread.
+    void resolvePromise();
+    void rejectPromise();
+
+private:
+    ScheduledSuspendContainer(double suspendTime, size_t suspendFrame, PassRefPtrWillBeRawPtr<ScriptPromiseResolver>);
+
+    // Actual suspend time before the quantization by render quantum frame.
+    double m_suspendTime;
+
+    // Suspend sample frame. This is quantized by the render quantum size.
+    size_t m_suspendFrame;
+
+    // Associated promise resolver.
+    RefPtrWillBePersistent<ScriptPromiseResolver> m_resolver;
+
+    ExceptionCode m_errorCode;
+    String m_errorMessage;
 };
 
 } // namespace blink
 
 #endif // OfflineAudioContext_h