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
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND ANY
  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  * DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (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/AudioContext.h"
+#include "wtf/HashMap.h"
 
 namespace blink {
 
 class ExceptionState;
+class ScheduledSuspendContainer;
+
+// The HashMap with 'zero' key is needed because |currentSampleFrame| can be zero.
+using SuspendContainerMap = HashMap<size_t, RefPtr<ScheduledSuspendContainer>, DefaultHash<size_t>::Hash, WTF::UnsignedWithZeroKeyHashTraits<size_t>>;

[haraken, 2015/07/08 04:05:41]

Actually this ScheduledSuspendContainer doesn't need to be a RefPtr, because it
must be guaranteed that the main thread keeps the ScheduledSuspendContainer
alive while the render thread uses the ScheduledSuspendContainer.

Maybe it is clearer to just use a raw pointer with a good comment.

[hongchan, 2015/07/08 17:47:32]

Done. However, I am having a cross-thread issue in
|resolveSuspendContainerOnMainThread()| method. Please have a look at the method
in the implementation file.

 
 class MODULES_EXPORT OfflineAudioContext final : public AudioContext {
     DEFINE_WRAPPERTYPEINFO();
 public:
     static OfflineAudioContext* create(ExecutionContext*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate, ExceptionState&);
 
     virtual ~OfflineAudioContext();
 
+    DECLARE_VIRTUAL_TRACE();
+
+    // Fire completion event when the rendering is finished.
+    void fireCompletionEvent() override;
+
+    // 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() override;
+
+    // Clear suspensions marked as 'resolved' in the list.
+    void resolvePendingSuspendPromises() override;
+
+    DEFINE_ATTRIBUTE_EVENT_LISTENER(complete);
+
     ScriptPromise startOfflineRendering(ScriptState*);
+    ScriptPromise suspendOfflineRendering(ScriptState*, double);
+    ScriptPromise resumeOfflineRendering(ScriptState*);
+
 private:
     OfflineAudioContext(Document*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate);
+
+    // 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(PassRefPtr<ScheduledSuspendContainer>);
+
+    // Reject a suspend container on the main thread when the validation fails.
+    void rejectSuspendContainerOnMainThread(PassRefPtr<ScheduledSuspendContainer>);
+
+    // Resolve a pending suspend container and removes it from the map.
+    void resolveSuspendContainerOnMainThread(PassRefPtr<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;

[haraken, 2015/07/08 04:05:41]

I'm not sure but would it be better to introduce a new state like NotStarted?

[hongchan, 2015/07/08 17:47:32]

rtoy@ and I thought about having a 'created' state, but then we need to change
the Web Audio API spec first. I agree with the idea, but I would like to discuss
it with the Audio WG and change the spec before I introduce a new state.

+
+    // Total render sample length.
+    size_t m_totalRenderFrames;
+};
+
+// A container class for a pair of time information and the suspend promise
+// resolver.
+//
+// TODO(hongchan): This class is |ThreadSafeRefCounted| because it needs to be
+// accessed by the offline render thread which is not oilpan-enabled. This is a
+// short-term solution until the offline render thread gets oilpan coverage.
+class ScheduledSuspendContainer : public ThreadSafeRefCounted<ScheduledSuspendContainer> {

[haraken, 2015/07/08 04:05:42]

As commented above, the render thread can keep ScheduledSuspendContainer with a
raw pointer. Then this doesn't need to be ThreadSafeRefCounted.

(It seems a bit strange to make a class that needs to be created and destructed
in the same thread ThreadSafeRefCounted.)

[hongchan, 2015/07/08 17:47:32]

Unfortunately, |resolvePendingSuspendPromises()| creates a local pointer in the
render thread to pass it to the main thread, and that violates the
|threadSafeBind()| method. Do you have a suggestion to avoid this error here?

+public:
+    static PassRefPtr<ScheduledSuspendContainer> create(double suspendTime, size_t suspendFrame, PassRefPtrWillBeRawPtr<ScriptPromiseResolver>);
+    ~ScheduledSuspendContainer();
+
+    double suspendTime() const { return m_suspendTime; }
+    size_t suspendFrame() const { return m_suspendFrame; }
+
+    // Query if the rendering should be suspended at |whenFrame|.
+    bool shouldSuspendAtFrame(size_t whenFrame) const;
+
+    // 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