AudioStream.h

/*
 * Copyright 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef OBOE_STREAM_H_
#define OBOE_STREAM_H_
 
#include <atomic>
#include <cstdint>
#include <ctime>
#include <mutex>
#include "oboe/Definitions.h"
#include "oboe/ResultWithValue.h"
#include "oboe/AudioStreamBuilder.h"
#include "oboe/AudioStreamBase.h"
#include "oboe/Utilities.h"
 
namespace oboe {
 
constexpr int64_t kDefaultTimeoutNanos = (2000 * kNanosPerMillisecond);
 
class AudioStream : public AudioStreamBase {
    friend class AudioStreamBuilder; // allow access to setWeakThis() and lockWeakThis()
public:
 
    AudioStream() {}
 
    explicit AudioStream(const AudioStreamBuilder &builder);
 
    virtual ~AudioStream();
 
    virtual Result open() {
        return Result::OK; // Called by subclasses. Might do more in the future.
    }
 
    virtual Result release() {
        return Result::ErrorUnimplemented;
    }
 
    virtual Result close();
 
    virtual Result start(int64_t timeoutNanoseconds = kDefaultTimeoutNanos);
 
    virtual Result pause(int64_t timeoutNanoseconds = kDefaultTimeoutNanos);
 
    virtual Result flush(int64_t timeoutNanoseconds = kDefaultTimeoutNanos);
 
    virtual Result stop(int64_t timeoutNanoseconds = kDefaultTimeoutNanos);
 
    /* Asynchronous requests.
     * Use waitForStateChange() if you need to wait for completion.
     */
 
    virtual Result requestStart() = 0;
 
    virtual Result requestPause() = 0;
 
    virtual Result requestFlush() = 0;
 
    virtual Result requestStop() = 0;
 
    virtual StreamState getState() = 0;
 
    virtual Result waitForStateChange(StreamState inputState,
                                          StreamState *nextState,
                                          int64_t timeoutNanoseconds) = 0;
 
    virtual ResultWithValue<int32_t> setBufferSizeInFrames(int32_t /* requestedFrames  */) {
        return Result::ErrorUnimplemented;
    }
 
    virtual ResultWithValue<int32_t> getXRunCount() {
        return ResultWithValue<int32_t>(Result::ErrorUnimplemented);
    }
 
    virtual bool isXRunCountSupported() const = 0;
 
    int32_t getFramesPerBurst() const {
        return mFramesPerBurst;
    }
 
    int32_t getBytesPerFrame() const {
        return isCompressedFormat(mFormat) ? 1 : mChannelCount * getBytesPerSample(); }
 
    int32_t getBytesPerSample() const;
 
    virtual int64_t getFramesWritten();
 
    virtual int64_t getFramesRead();
 
    virtual ResultWithValue<double> calculateLatencyMillis() {
        return ResultWithValue<double>(Result::ErrorUnimplemented);
    }
 
    virtual Result getTimestamp(clockid_t /* clockId  */,
                                int64_t* /* framePosition */,
                                int64_t* /* timeNanoseconds */) {
        return Result::ErrorUnimplemented;
    }
 
    virtual ResultWithValue<FrameTimestamp> getTimestamp(clockid_t /* clockId */);
 
    // ============== I/O ===========================
    virtual ResultWithValue<int32_t> write(const void* /* buffer */,
                             int32_t /* numFrames */,
                             int64_t /* timeoutNanoseconds */ ) {
        return ResultWithValue<int32_t>(Result::ErrorUnimplemented);
    }
 
    virtual ResultWithValue<int32_t> read(void* /* buffer */,
                            int32_t /* numFrames */,
                            int64_t /* timeoutNanoseconds */) {
        return ResultWithValue<int32_t>(Result::ErrorUnimplemented);
    }
 
    virtual AudioApi getAudioApi() const = 0;
 
    bool usesAAudio() const {
        return getAudioApi() == AudioApi::AAudio;
    }
 
    virtual void *getUnderlyingStream() const {
        return nullptr;
    }
 
    virtual void updateFramesWritten() = 0;
 
    virtual void updateFramesRead() = 0;
 
    /*
     * Swap old callback for new callback.
     * This not atomic.
     * This should only be used internally.
     * @param dataCallback
     * @return previous dataCallback
     */
    AudioStreamDataCallback *swapDataCallback(AudioStreamDataCallback *dataCallback) {
        AudioStreamDataCallback *previousCallback = mDataCallback;
        mDataCallback = dataCallback;
        return previousCallback;
    }
 
    /*
     * Swap old partial data callback for new callback.
     * This not atomic.
     * This should only be used internally.
     * @param dataCallback
     * @return previous dataCallback
     */
    AudioStreamPartialDataCallback *swapPartialDataCallback(
            AudioStreamPartialDataCallback *partialDataCallback) {
        AudioStreamPartialDataCallback *previousPartialCallback = mPartialDataCallback;
        mPartialDataCallback = partialDataCallback;
        return previousPartialCallback;
    }
 
    /*
     * Swap old callback for new callback.
     * This not atomic.
     * This should only be used internally.
     * @param errorCallback
     * @return previous errorCallback
     */
    AudioStreamErrorCallback *swapErrorCallback(AudioStreamErrorCallback *errorCallback) {
        AudioStreamErrorCallback *previousCallback = mErrorCallback;
        mErrorCallback = errorCallback;
        return previousCallback;
    }
 
    ResultWithValue<int32_t> getAvailableFrames();
 
    ResultWithValue<int32_t> waitForAvailableFrames(int32_t numFrames,
                                                    int64_t timeoutNanoseconds);
 
    virtual oboe::Result getLastErrorCallbackResult() const {
        return mErrorCallbackResult;
    }
 
 
    int32_t getDelayBeforeCloseMillis() const {
        return mDelayBeforeCloseMillis;
    }
 
    void setDelayBeforeCloseMillis(int32_t delayBeforeCloseMillis) {
        mDelayBeforeCloseMillis = delayBeforeCloseMillis;
    }
 
    void setPerformanceHintEnabled(bool enabled) {
        mPerformanceHintEnabled = enabled;
    }
 
    bool isPerformanceHintEnabled() {
        return mPerformanceHintEnabled;
    }
 
    virtual oboe::Result reportWorkload([[maybe_unused]] int32_t appWorkload) {
        return oboe::Result::ErrorUnimplemented;
    }
 
    virtual oboe::Result notifyWorkloadIncrease([[maybe_unused]] bool cpu,
                                                [[maybe_unused]] bool gpu,
                                                [[maybe_unused]] const char* debugName) {
        return oboe::Result::ErrorUnimplemented;
    }
 
    virtual oboe::Result notifyWorkloadReset([[maybe_unused]] bool cpu,
                                             [[maybe_unused]] bool gpu,
                                             [[maybe_unused]] const char* debugName) {
        return oboe::Result::ErrorUnimplemented;
    }
 
    virtual oboe::Result notifyWorkloadSpike([[maybe_unused]] bool cpu,
                                             [[maybe_unused]] bool gpu,
                                             [[maybe_unused]] const char* debugName) {
        return oboe::Result::ErrorUnimplemented;
    }
 
    virtual oboe::Result setOffloadDelayPadding([[maybe_unused]] int32_t delayInFrames,
                                                [[maybe_unused]] int32_t paddingInFrames) {
        return Result::ErrorUnimplemented;
    }
 
    virtual ResultWithValue<int32_t> getOffloadDelay() {
        return ResultWithValue<int32_t>(Result::ErrorUnimplemented);
    }
 
    virtual ResultWithValue<int32_t> getOffloadPadding() {
        return ResultWithValue<int32_t>(Result::ErrorUnimplemented);
    }
 
    virtual oboe::Result setOffloadEndOfStream() {
        return Result::ErrorUnimplemented;
    }
 
    virtual ResultWithValue<int64_t> flushFromFrame([[maybe_unused]] FlushFromAccuracy accuracy,
                                                    [[maybe_unused]] int64_t positionInFrames) {
        return ResultWithValue<int64_t>(Result::ErrorUnimplemented);
    }
 
    virtual oboe::Result setPlaybackParameters(
            [[maybe_unused]] const PlaybackParameters& parameters) {
        return Result::ErrorUnimplemented;
    }
 
    virtual ResultWithValue<PlaybackParameters> getPlaybackParameters() {
        return ResultWithValue<PlaybackParameters>(Result::ErrorUnimplemented);
    }
 
    /*
     * Make a shared_ptr that will prevent this stream from being deleted.
     */
    std::shared_ptr<oboe::AudioStream> lockWeakThis() {
        return mWeakThis.lock();
    }
 
    AudioStream *getParentStream() const {
        return mParentStream;
    }
 
    bool hasParentStream() const {
        return mHasParentStream;
    }
 
    void setParentStream(AudioStream *parentStream) {
        mParentStream = parentStream;
        mHasParentStream = parentStream != nullptr;
    }
 
protected:
 
    bool wasErrorCallbackCalled() {
        return mErrorCallbackCalled.exchange(true);
    }
 
    virtual Result waitForStateTransition(StreamState startingState,
                                          StreamState endingState,
                                          int64_t timeoutNanoseconds);
 
    virtual DataCallbackResult onDefaultCallback(void* /* audioData  */, int /* numFrames */) {
        return DataCallbackResult::Stop;
    }
 
    virtual DataCallbackResult fireDataCallback(void *audioData, int numFrames);
 
    virtual int32_t firePartialDataCallback(void* audioData, int numFrames);
 
    bool isDataCallbackEnabled() {
        return mDataCallbackEnabled;
    }
 
    void setDataCallbackEnabled(bool enabled) {
        mDataCallbackEnabled = enabled;
    }
 
    void calculateDefaultDelayBeforeCloseMillis();
 
    void sleepBeforeClose() {
        if (mDelayBeforeCloseMillis > 0) {
            usleep(mDelayBeforeCloseMillis * 1000);
        }
    }
 
    virtual void beginPerformanceHintInCallback() {}
 
    virtual void endPerformanceHintInCallback(int32_t /*numFrames*/) {}
 
    virtual void closePerformanceHint() {}
 
    /*
     * Set a weak_ptr to this stream from the shared_ptr so that we can
     * later use a shared_ptr in the error callback.
     */
    void setWeakThis(std::shared_ptr<oboe::AudioStream> &sharedStream) {
        mWeakThis = sharedStream;
    }
 
    std::weak_ptr<AudioStream> mWeakThis; // weak pointer to this object
 
    // Pointer to parent stream.
    // Non-empty only when wrapped by another AudioStream.
    AudioStream *mParentStream{};
 
    // Flag to indicate whether this stream is wrapped by a parent.
    bool mHasParentStream{};
 
    std::atomic<int64_t> mFramesWritten{};
 
    std::atomic<int64_t> mFramesRead{};
 
    std::mutex           mLock; // for synchronizing start/stop/close
 
    oboe::Result         mErrorCallbackResult = oboe::Result::OK;
 
    int32_t              mFramesPerBurst = kUnspecified;
 
    // Time to sleep in order to prevent a race condition with a callback after a close().
    // Two milliseconds may be enough but 10 msec is even safer.
    static constexpr int kMinDelayBeforeCloseMillis = 10;
    static constexpr int kMaxDelayBeforeCloseMillis = 100;
    int32_t              mDelayBeforeCloseMillis = kMinDelayBeforeCloseMillis;
 
private:
 
    // Log the scheduler if it changes.
    void                 checkScheduler();
    int                  mPreviousScheduler = -1;
 
    std::atomic<bool>    mDataCallbackEnabled{false};
    std::atomic<bool>    mErrorCallbackCalled{false};
 
    std::atomic<bool>    mPerformanceHintEnabled{false}; // set only by app
};
 
    struct StreamDeleterFunctor {
        void operator()(AudioStream  *audioStream) {
            if (audioStream) {
                audioStream->close();
            }
            delete audioStream;
        }
    };
} // namespace oboe
 
#endif /* OBOE_STREAM_H_ */