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/nbaio/SingleStateQueue.h>
23 #include <media/nbaio/NBAIO.h>
24 
25 namespace android {
26 
27 typedef 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.
35 class MonoPipe : public NBAIO_Sink {
36 
37     friend class MonoPipeReader;
38 
39 public:
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()
getAvgFrames()68             size_t  getAvgFrames() const { return mSetpoint; }
69             void    setAvgFrames(size_t setpoint);
maxFrames()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 
86 private:
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