Implement suspend() and resume() for OfflineAudioContext

third_party/WebKit/Source/modules/webaudio/OfflineAudioContext.cpp

Index: third_party/WebKit/Source/modules/webaudio/OfflineAudioContext.cpp
diff --git a/third_party/WebKit/Source/modules/webaudio/OfflineAudioContext.cpp b/third_party/WebKit/Source/modules/webaudio/OfflineAudioContext.cpp
index b95e4da61988f5074ebc95145d4682c63b41c476..35851062855040ac14ce658ea94c309ba5d7126a 100644
--- a/third_party/WebKit/Source/modules/webaudio/OfflineAudioContext.cpp
+++ b/third_party/WebKit/Source/modules/webaudio/OfflineAudioContext.cpp
@@ -32,6 +32,10 @@
 #include "core/dom/Document.h"
 #include "core/dom/ExceptionCode.h"
 #include "core/dom/ExecutionContext.h"
+#include "modules/webaudio/DeferredTaskHandler.h"
+#include "modules/webaudio/OfflineAudioCompletionEvent.h"
+#include "modules/webaudio/OfflineAudioDestinationNode.h"
+
 #include "platform/audio/AudioUtilities.h"
 
 namespace blink {
@@ -76,7 +80,7 @@ OfflineAudioContext* OfflineAudioContext::create(ExecutionContext* context, unsi
         return nullptr;
     }
 
-    OfflineAudioContext* audioContext = new OfflineAudioContext(document, numberOfChannels, numberOfFrames, sampleRate);
+    OfflineAudioContext* audioContext = new OfflineAudioContext(document, numberOfChannels, numberOfFrames, sampleRate, exceptionState);
 
     if (!audioContext->destination()) {
         exceptionState.throwDOMException(
@@ -91,19 +95,47 @@ OfflineAudioContext* OfflineAudioContext::create(ExecutionContext* context, unsi
     return audioContext;
 }
 
-OfflineAudioContext::OfflineAudioContext(Document* document, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate)
+OfflineAudioContext::OfflineAudioContext(Document* document, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate, ExceptionState& exceptionState)
     : AbstractAudioContext(document, numberOfChannels, numberOfFrames, sampleRate)
+    , m_isRenderingStarted(false)
+    , m_totalRenderFrames(numberOfFrames)
 {
+    // Create a new destination for offline rendering.
+    m_renderTarget = AudioBuffer::create(numberOfChannels, numberOfFrames, sampleRate);
+
+    // Throw an exception if the render target is not ready.
+    if (!m_renderTarget) {
+        exceptionState.throwDOMException(InvalidAccessError,

[Raymond Toy, 2015/10/21 23:14:18]

I think the CL was using RangeError for arrays that can't be allocated.

[hongchan, 2015/10/22 18:23:49]

Done.

+            "failed to create a target buffer for offline audio rendering.");

[Raymond Toy, 2015/10/21 23:14:18]

Include the the requested number of frames and number of channels in the
message.

[hongchan, 2015/10/22 18:23:49]

Done.

+    }
+
+    // TODO(hongchan): throw an exception when the buffer creation fails.
+    if (m_renderTarget.get())
+        m_destinationNode = OfflineAudioDestinationNode::create(this, m_renderTarget.get());
+
+    initialize();
 }
 
 OfflineAudioContext::~OfflineAudioContext()
 {
 }
 
+DEFINE_TRACE(OfflineAudioContext)
+{
+    visitor->trace(m_renderTarget);
+    visitor->trace(m_completeResolver);
+    visitor->trace(m_scheduledSuspends);
+    AbstractAudioContext::trace(visitor);
+}
+
 ScriptPromise OfflineAudioContext::startOfflineRendering(ScriptState* scriptState)
 {
+    ASSERT(isMainThread());
+
     // Calling close() on an OfflineAudioContext is not supported/allowed,
     // but it might well have been stopped by its execution context.
+    //
+    // See: crbug.com/435867
     if (isContextClosed()) {
         return ScriptPromise::rejectWithDOMException(
             scriptState,
@@ -112,8 +144,17 @@ ScriptPromise OfflineAudioContext::startOfflineRendering(ScriptState* scriptStat
                 "cannot call startRendering on an OfflineAudioContext in a stopped state."));
     }
 
-    if (m_offlineResolver) {
-        // Can't call startRendering more than once.  Return a rejected promise now.
+    // If the context is not in the suspended state (i.e. running), reject the promise.
+    if (contextState() != AudioContextState::Suspended) {
+        return ScriptPromise::rejectWithDOMException(
+            scriptState,
+            DOMException::create(
+                InvalidStateError,
+                "cannot startRendering when an OfflineAudioContext is " + state()));
+    }
+
+    // Can't call startRendering more than once.  Return a rejected promise now.
+    if (m_isRenderingStarted) {
         return ScriptPromise::rejectWithDOMException(
             scriptState,
             DOMException::create(
@@ -121,34 +162,233 @@ ScriptPromise OfflineAudioContext::startOfflineRendering(ScriptState* scriptStat
                 "cannot call startRendering more than once"));
     }
 
-    m_offlineResolver = ScriptPromiseResolver::create(scriptState);
-    startRendering();
-    return m_offlineResolver->promise();
+    ASSERT(!m_isRenderingStarted);
+
+    m_completeResolver = ScriptPromiseResolver::create(scriptState);
+
+    // Start rendering and return the promise.
+    m_isRenderingStarted = true;
+    setContextState(Running);
+    destinationHandler().startRendering();
+
+    return m_completeResolver->promise();
 }
 
 ScriptPromise OfflineAudioContext::closeContext(ScriptState* scriptState)
 {
     return ScriptPromise::rejectWithDOMException(
         scriptState,
-        DOMException::create(InvalidAccessError, "cannot close an OfflineAudioContext."));
+        DOMException::create(
+            InvalidAccessError,
+            "cannot close an OfflineAudioContext."));
 }
 
-ScriptPromise OfflineAudioContext::suspendContext(ScriptState* scriptState)
+ScriptPromise OfflineAudioContext::suspendContext(ScriptState* scriptState, double when)
 {
-    return ScriptPromise::rejectWithDOMException(
-        scriptState,
-        DOMException::create(
-            InvalidAccessError,
-            "cannot suspend an OfflineAudioContext"));
+    ASSERT(isMainThread());
+
+    ScriptPromiseResolver* resolver = ScriptPromiseResolver::create(scriptState);
+    ScriptPromise promise = resolver->promise();
+
+    // The render thread does not exist; reject the promise.
+    if (!destinationHandler().offlineRenderThread()) {
+        resolver->reject(DOMException::create(InvalidStateError,
+            "the rendering is already finished"));
+        return promise;
+    }
+
+    // The specified suspend time is negative; reject the promise.
+    if (when < 0) {
+        resolver->reject(DOMException::create(InvalidStateError,
+            "negative suspend time (" + String::number(when) + ") is not allowed"));
+        return promise;
+    }
+
+    // Quantize (to the lower boundary) the suspend time by the render quantum.
+    size_t frame = when * sampleRate();
+    frame -= frame % destinationHandler().renderQuantumFrames();
+
+    // The suspend time should be earlier than the total render frame. If the
+    // requested suspension time is equal to the total render frame, the promise
+    // will be rejected.
+    if (m_totalRenderFrames <= frame) {
+        resolver->reject(DOMException::create(InvalidStateError,
+            "cannot schedule a suspend at frame " + String::number(frame) +
+            " (" + String::number(when) + " seconds) " +
+            "because it is greater than or equal to the total render duration of " +
+            String::number(m_totalRenderFrames) + " frames"));
+        return promise;
+    }
+
+    // The specified suspend time is in the past; reject the promise.
+    if (frame < currentSampleFrame()) {
+        resolver->reject(DOMException::create(InvalidStateError,
+            "cannot schedule a suspend at frame " +
+            String::number(frame) + " (" + String::number(when) +
+            " seconds) because it is earlier than the current frame of " +
+            String::number(currentSampleFrame()) + " (" +
+            String::number(currentTime()) + " seconds)"));
+        return promise;
+    }
+
+    // If there is a duplicate suspension at the same quantized frame,
+    // reject the promise.
+    if (m_scheduledSuspends.contains(frame)) {
+        resolver->reject(DOMException::create(InvalidStateError,
+            "cannot schedule more than one suspend at frame " +
+            String::number(frame) + " (" +
+            String::number(when) + " seconds)"));
+        return promise;
+    }
+
+    // Wait until the suspend map is available for the insertion.
+    AutoLocker locker(this);

[Raymond Toy, 2015/10/21 23:14:18]

AutoLocker or OfflineAutoLocker?  Add a comment to explain which.  It's not
immediately obvious to me.

[hongchan, 2015/10/22 18:23:49]

This gets called in the main thread. It needs to be AutoLocker. We are better
off changing the name to 'MainThreadAutoLocker' or something like that, but that
should be another CL.

+
+    m_scheduledSuspends.add(frame, resolver);
+
+    return promise;
 }
 
 ScriptPromise OfflineAudioContext::resumeContext(ScriptState* scriptState)
 {
+    ASSERT(isMainThread());
+
+    ScriptPromiseResolver* resolver = ScriptPromiseResolver::create(scriptState);
+    ScriptPromise promise = resolver->promise();
+
+    // If the rendering has not started, reject the promise.
+    if (!m_isRenderingStarted) {
+        resolver->reject(DOMException::create(InvalidStateError,
+            "cannot resume an offline context that has not started"));
+        return promise;
+    }
+
+    // If the context is not in a suspended or closed state, reject the promise.
+    // TODO(hongchan): there is a conflict in the spec regarding resuming a

[Raymond Toy, 2015/10/21 23:14:18]

If you have the crbug number, add that too.

+    // running context. Per the current spec, the implementation here rejects
+    // the promise for resuming a running context.
+    if (contextState() != AudioContextState::Suspended) {
+        resolver->reject(DOMException::create(InvalidStateError,
+            "cannot resume an offline context that is " + state()));
+        return promise;
+    }
+
+    // If the context is suspended, resume rendering by setting the state to
+    // "Running." and calling startRendering(). Note that resuming is possible
+    // only after the rendering started.
+    setContextState(Running);
+    destinationHandler().startRendering();
+
+    // Resolve the promise immediately.
+    resolver->resolve();
+
+    return promise;
+}
+
+ScriptPromise OfflineAudioContext::suspendContext(ScriptState* scriptState)
+{
+    // This CANNOT be called on OfflineAudioContext; this is only to implement
+    // the pure virtual interface from AbstractAudioContext.
+    RELEASE_ASSERT_NOT_REACHED();
+
     return ScriptPromise::rejectWithDOMException(
         scriptState,
         DOMException::create(
-            InvalidAccessError,
-            "cannot resume an OfflineAudioContext"));
+            InvalidStateError,
+            "cannot suspend offline audio context without the specified time."));
+}
+
+void OfflineAudioContext::fireCompletionEvent()
+{
+    ASSERT(isMainThread());
+
+    // We set the state to closed here so that the oncomplete event handler sees
+    // that the context has been closed.
+    setContextState(Closed);
+
+    AudioBuffer* renderedBuffer = renderTarget();
+
+    ASSERT(renderedBuffer);
+    if (!renderedBuffer)
+        return;
+
+    // Avoid firing the event if the document has already gone away.
+    if (executionContext()) {
+        // Call the offline rendering completion event listener and resolve the
+        // promise too.
+        dispatchEvent(OfflineAudioCompletionEvent::create(renderedBuffer));
+        m_completeResolver->resolve(renderedBuffer);
+    } else {
+        // The resolver should be rejected when the execution context is gone.
+        m_completeResolver->reject(DOMException::create(InvalidStateError,
+            "the execution context does not exist"));
+    }
+}
+
+bool OfflineAudioContext::handlePreOfflineRenderTasks()
+{
+    ASSERT(isAudioThread());
+
+    // OfflineAutoLocker here locks the render thread for this scope and it is
+    // safe to lock the offline rendering because it does not have to be careful
+    // about glitches as opposed to the real-time rendering. It is also
+    // necessary to avoid tryLock() inside of this auto locker because the
+    // timing of suspension MUST NOT be delayed.
+    OfflineAutoLocker locker(this);

[Raymond Toy, 2015/10/21 23:14:18]

I only seem to be able to see OfflineAudioLocker being used in handlePre and
post offline tasks.  Shouldn't there be a call somewhere on the main thread? 
Otherwise, I don't understand what really needs to be locked.

[hongchan, 2015/10/22 18:23:49]

OfflineAutoLocker can be called from the AudioThread. We cannot use AutoLocker
when it's called from the audio thread because it is designed to be called only
from the main thread.

Note that both of them does the exactly same thing (locking m_contextGraphMutex)
but they are originated from different threads.

I suggest we should change the names of AutoLocker/OfflineAutoLocker as whole,
but that should be another CL. Probably
MainThreadAutoLocker/AudioThreadAutoLocker might be more explicit and clearer.

+
+    deferredTaskHandler().handleDeferredTasks();
+    handleStoppableSourceNodes();
+
+    return shouldSuspend();
+}
+
+void OfflineAudioContext::handlePostOfflineRenderTasks()
+{
+    ASSERT(isAudioThread());
+
+    // OfflineAutoLocker here locks the render thread for this scope and it is
+    // safe to lock the offline rendering because of the same reason described
+    // in |handlePreOfflineRenderTasks|.
+    OfflineAutoLocker locker(this);
+
+    deferredTaskHandler().breakConnections();
+    releaseFinishedSourceNodes();
+    deferredTaskHandler().handleDeferredTasks();
+    deferredTaskHandler().requestToDeleteHandlersOnMainThread();
+}
+
+
+OfflineAudioDestinationHandler& OfflineAudioContext::destinationHandler()
+{
+    return static_cast<OfflineAudioDestinationHandler&>(destination()->audioDestinationHandler());
+}
+
+void OfflineAudioContext::resolveSuspendOnMainThread(size_t frame)
+{
+    ASSERT(isMainThread());
+
+    // Suspend the context first. This will fire onstatechange event.
+    setContextState(Suspended);
+
+    ASSERT(m_scheduledSuspends.contains(frame));
+
+    // Wait until the suspend map is available for the removal.
+    AutoLocker locker(this);
+
+    SuspendMap::iterator it = m_scheduledSuspends.find(frame);
+    it->value->resolve();
+
+    m_scheduledSuspends.remove(it);
+}
+
+bool OfflineAudioContext::shouldSuspend()
+{
+    ASSERT(isAudioThread());
+
+    if (m_scheduledSuspends.contains(currentSampleFrame()))
+        return true;
+
+    return false;
 }
 
 } // namespace blink