1/*
2 * Copyright (C) 2012 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ANDROID_AUDIO_MONO_PIPE_H
18#define ANDROID_AUDIO_MONO_PIPE_H
19
20#include <time.h>
21#include <audio_utils/fifo.h>
22#include <media/SingleStateQueue.h>
23#include "NBAIO.h"
24
25namespace android {
26
27typedef SingleStateQueue<ExtendedTimestamp> ExtendedTimestampSingleStateQueue;
28
29// MonoPipe is similar to Pipe except:
30//  - supports only a single reader, called MonoPipeReader
31//  - write() cannot overrun; instead it will return a short actual count if insufficient space
32//  - write() can optionally block if the pipe is full
33// Like Pipe, it is not multi-thread safe for either writer or reader
34// but writer and reader can be different threads.
35class MonoPipe : public NBAIO_Sink {
36
37    friend class MonoPipeReader;
38
39public:
40    // reqFrames will be rounded up to a power of 2, and all slots are available. Must be >= 2.
41    // Note: whatever shares this object with another thread needs to do so in an SMP-safe way (like
42    // creating it the object before creating the other thread, or storing the object with a
43    // release_store). Otherwise the other thread could see a partially-constructed object.
44    MonoPipe(size_t reqFrames, const NBAIO_Format& format, bool writeCanBlock = false);
45    virtual ~MonoPipe();
46
47    // NBAIO_Port interface
48
49    //virtual ssize_t negotiate(const NBAIO_Format offers[], size_t numOffers,
50    //                          NBAIO_Format counterOffers[], size_t& numCounterOffers);
51    //virtual NBAIO_Format format() const;
52
53    // NBAIO_Sink interface
54
55    //virtual int64_t framesWritten() const;
56    //virtual int64_t framesUnderrun() const;
57    //virtual int64_t underruns() const;
58
59    // returns n where 0 <= n <= mMaxFrames, or a negative status_t
60    // including the private status codes in NBAIO.h
61    virtual ssize_t availableToWrite();
62
63    virtual ssize_t write(const void *buffer, size_t count);
64    //virtual ssize_t writeVia(writeVia_t via, size_t total, void *user, size_t block);
65
66            // average number of frames present in the pipe under normal conditions.
67            // See throttling mechanism in MonoPipe::write()
68            size_t  getAvgFrames() const { return mSetpoint; }
69            void    setAvgFrames(size_t setpoint);
70            size_t  maxFrames() const { return mMaxFrames; }
71
72            // Set the shutdown state for the write side of a pipe.
73            // This may be called by an unrelated thread.  When shutdown state is 'true',
74            // a write that would otherwise block instead returns a short transfer count.
75            // There is no guarantee how long it will take for the shutdown to be recognized,
76            // but it will not be an unbounded amount of time.
77            // The state can be restored to normal by calling shutdown(false).
78            void    shutdown(bool newState = true);
79
80            // Return true if the write side of a pipe is currently shutdown.
81            bool    isShutdown();
82
83            // Return NO_ERROR if there is a timestamp available
84            status_t getTimestamp(ExtendedTimestamp &timestamp);
85
86private:
87    const size_t    mMaxFrames;     // as requested in constructor, rounded up to a power of 2
88    void * const    mBuffer;
89    audio_utils_fifo        mFifo;
90    audio_utils_fifo_writer mFifoWriter;
91    bool            mWriteTsValid;  // whether mWriteTs is valid
92    struct timespec mWriteTs;       // time that the previous write() completed
93    size_t          mSetpoint;      // target value for pipe fill depth
94    const bool      mWriteCanBlock; // whether write() should block if the pipe is full
95
96    bool            mIsShutdown;    // whether shutdown(true) was called, no barriers are needed
97
98    ExtendedTimestampSingleStateQueue::Shared      mTimestampShared;
99    ExtendedTimestampSingleStateQueue::Mutator     mTimestampMutator;
100    ExtendedTimestampSingleStateQueue::Observer    mTimestampObserver;
101};
102
103}   // namespace android
104
105#endif  // ANDROID_AUDIO_MONO_PIPE_H
106