| /* |
| * Copyright (C) 2015 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 ANDROID_AUDIO_FIFO_H |
| #define ANDROID_AUDIO_FIFO_H |
| |
| #include <stdlib.h> |
| #include <sys/types.h> |
| #include <audio_utils/fifo_index.h> |
| |
| #ifndef __cplusplus |
| #error C API is no longer supported |
| #endif |
| |
| /** Indicates whether index is multi-thread safe, and the synchronization technique. */ |
| enum audio_utils_fifo_sync { |
| /** Index is not multi-thread safe. No support for synchronization or timeouts. */ |
| AUDIO_UTILS_FIFO_SYNC_SINGLE_THREADED, |
| /** Index is multi-thread safe. Synchronization is by polling, timeouts by clock_nanosleep(). */ |
| AUDIO_UTILS_FIFO_SYNC_SLEEP, |
| /** Index is multi-thread safe. Synchronization is by futex mapped in one process. */ |
| AUDIO_UTILS_FIFO_SYNC_PRIVATE, |
| /** Index is multi-thread safe. Synchronization is by futex mapped in one or more processes. */ |
| AUDIO_UTILS_FIFO_SYNC_SHARED, |
| }; |
| |
| /** |
| * Base class for single-writer, single-reader or multi-reader, optionally blocking FIFO. |
| * The base class manipulates frame indices only, and has no knowledge of frame sizes or the buffer. |
| * At most one reader, called the "throttling reader", can block the writer. |
| * The "fill level", or unread frame count, is defined with respect to the throttling reader. |
| */ |
| class audio_utils_fifo_base { |
| |
| public: |
| |
| /** |
| * Return the capacity, or statically configured maximum frame count. |
| * |
| * \return The capacity in frames. |
| */ |
| uint32_t capacity() const |
| { return mFrameCount; } |
| |
| protected: |
| |
| /** |
| * Construct FIFO base class |
| * |
| * \param frameCount Maximum usable frames to be stored in the FIFO > 0 && <= INT32_MAX, |
| * aka "capacity". |
| * If release()s always use the same count, and the count is a divisor of |
| * (effective) \p frameCount, then the obtain()s won't ever be fragmented. |
| * \param writerRear Writer's rear index. Passed by reference because it must be non-NULL. |
| * \param throttleFront Pointer to the front index of at most one reader that throttles the |
| * writer, or NULL for no throttling. |
| * \param sync Index synchronization, defaults to AUDIO_UTILS_FIFO_SYNC_SHARED but can |
| * also be any other value. |
| */ |
| audio_utils_fifo_base(uint32_t frameCount, audio_utils_fifo_index& writerRear, |
| audio_utils_fifo_index *throttleFront = NULL, |
| audio_utils_fifo_sync sync = AUDIO_UTILS_FIFO_SYNC_SHARED); |
| /*virtual*/ ~audio_utils_fifo_base(); |
| |
| /** Return a new index as the sum of a validated index and a specified increment. |
| * |
| * \param index Caller should supply a validated mFront or mRear. |
| * \param increment Value to be added to the index <= mFrameCount. |
| * |
| * \return The sum of index plus increment. |
| */ |
| uint32_t sum(uint32_t index, uint32_t increment) const; |
| |
| /** Return the difference between two indices: rear - front. |
| * |
| * \param rear Caller should supply an unvalidated mRear. |
| * \param front Caller should supply an unvalidated mFront. |
| * \param lost If non-NULL, set to the approximate number of frames lost before |
| * re-synchronization when -EOVERFLOW occurs, or set to zero when no frames lost. |
| * \param flush Whether to flush the entire buffer on -EOVERFLOW. |
| * |
| * \return The zero or positive difference <= mFrameCount, or a negative error code. |
| * \retval -EIO corrupted indices, no recovery is possible |
| * \retval -EOVERFLOW reader doesn't throttle writer, and frames were lost because reader |
| * isn't keeping up with writer; see \p lost |
| */ |
| int32_t diff(uint32_t rear, uint32_t front, size_t *lost = NULL, bool flush = false) const; |
| |
| /** |
| * Mark the FIFO as shutdown (permanently unusable), usually due to an -EIO status from an API. |
| * Thereafter, all APIs that return a status will return -EIO, and other APIs will be no-ops. |
| */ |
| void shutdown() const; |
| |
| // These fields are const after initialization |
| |
| /** Maximum usable frames to be stored in the FIFO > 0 && <= INT32_MAX, aka "capacity". */ |
| const uint32_t mFrameCount; |
| /** Equal to roundup(mFrameCount). */ |
| const uint32_t mFrameCountP2; |
| |
| /** |
| * Equal to mFrameCountP2 - mFrameCount, the number of "wasted" frames after the end of mBuffer. |
| * Only the indices are wasted, not any memory. |
| */ |
| const uint32_t mFudgeFactor; |
| |
| /** Reference to writer's rear index. */ |
| audio_utils_fifo_index& mWriterRear; |
| /** Indicates how synchronization is done for mWriterRear. */ |
| const audio_utils_fifo_sync mWriterRearSync; |
| |
| /** |
| * Pointer to the front index of at most one reader that throttles the writer, |
| * or NULL for no throttling. |
| */ |
| audio_utils_fifo_index* const mThrottleFront; |
| /** Indicates how synchronization is done for mThrottleFront. */ |
| const audio_utils_fifo_sync mThrottleFrontSync; |
| |
| /** Whether FIFO is marked as shutdown due to detection of an "impossible" error condition. */ |
| mutable bool mIsShutdown; |
| }; |
| |
| //////////////////////////////////////////////////////////////////////////////// |
| |
| /** |
| * Same as audio_utils_fifo_base, but understands frame sizes and knows about the buffer but does |
| * not own it. |
| */ |
| class audio_utils_fifo : public audio_utils_fifo_base { |
| |
| friend class audio_utils_fifo_reader; |
| friend class audio_utils_fifo_writer; |
| template <typename T> friend class audio_utils_fifo_writer_T; |
| |
| public: |
| |
| /** |
| * Construct a FIFO object: multi-process. |
| * Index synchronization is not configurable; it is always AUDIO_UTILS_FIFO_SYNC_SHARED. |
| * |
| * \param frameCount Maximum usable frames to be stored in the FIFO > 0 && <= INT32_MAX, |
| * aka "capacity". |
| * If writes and reads always use the same count, and the count is a divisor |
| * of \p frameCount, then the writes and reads won't do a partial transfer. |
| * \param frameSize Size of each frame in bytes > 0, |
| * \p frameSize * \p frameCount <= INT32_MAX. |
| * \param buffer Pointer to a non-NULL caller-allocated buffer of \p frameCount frames. |
| * \param writerRear Writer's rear index. Passed by reference because it must be non-NULL. |
| * \param throttleFront Pointer to the front index of at most one reader that throttles the |
| * writer, or NULL for no throttling. |
| */ |
| audio_utils_fifo(uint32_t frameCount, uint32_t frameSize, void *buffer, |
| audio_utils_fifo_index& writerRear, audio_utils_fifo_index *throttleFront = NULL); |
| |
| /** |
| * Construct a FIFO object: single-process. |
| * \param frameCount Maximum usable frames to be stored in the FIFO > 0 && <= INT32_MAX, |
| * aka "capacity". |
| * If writes and reads always use the same count, and the count is a divisor |
| * of \p frameCount, then the writes and reads won't do a partial transfer. |
| * \param frameSize Size of each frame in bytes > 0, |
| * \p frameSize * \p frameCount <= INT32_MAX. |
| * \param buffer Pointer to a non-NULL caller-allocated buffer of \p frameCount frames. |
| * \param throttlesWriter Whether there is one reader that throttles the writer. |
| * \param sync Index synchronization, defaults to AUDIO_UTILS_FIFO_SYNC_PRIVATE but can |
| * also be AUDIO_UTILS_FIFO_SYNC_SINGLE_THREADED or AUDIO_UTILS_FIFO_SYNC_SLEEP. |
| * AUDIO_UTILS_FIFO_SYNC_SHARED is not permitted. |
| */ |
| audio_utils_fifo(uint32_t frameCount, uint32_t frameSize, void *buffer, |
| bool throttlesWriter = true, |
| audio_utils_fifo_sync sync = AUDIO_UTILS_FIFO_SYNC_PRIVATE); |
| |
| /*virtual*/ ~audio_utils_fifo(); |
| |
| /** |
| * Return the frame size in bytes. |
| * |
| * \return frame size in bytes, always > 0. |
| */ |
| uint32_t frameSize() const |
| { return mFrameSize; } |
| |
| /** |
| * Return a pointer to the caller-allocated buffer. |
| * |
| * \return non-NULL pointer to buffer. |
| */ |
| void *buffer() const |
| { return mBuffer; } |
| |
| private: |
| // These fields are const after initialization |
| const uint32_t mFrameSize; // size of each frame in bytes |
| void * const mBuffer; // non-NULL pointer to caller-allocated buffer |
| // of size mFrameCount frames |
| |
| // only used for single-process constructor |
| audio_utils_fifo_index mSingleProcessSharedRear; |
| |
| // only used for single-process constructor when throttlesWriter == true |
| audio_utils_fifo_index mSingleProcessSharedFront; |
| }; |
| |
| /** |
| * Describes one virtually contiguous fragment of a logically contiguous slice. |
| * Compare to struct iovec for readv(2) and writev(2). |
| */ |
| struct audio_utils_iovec { |
| /** Offset of fragment in frames, relative to mBuffer, undefined if mLength == 0 */ |
| uint32_t mOffset; |
| /** Length of fragment in frames, 0 means fragment is empty */ |
| uint32_t mLength; |
| }; |
| |
| //////////////////////////////////////////////////////////////////////////////// |
| |
| /** |
| * Based on frameworks/av/include/media/AudioBufferProvider.h |
| */ |
| class audio_utils_fifo_provider { |
| public: |
| audio_utils_fifo_provider(audio_utils_fifo& fifo); |
| virtual ~audio_utils_fifo_provider(); |
| |
| /** |
| * Obtain access to a logically contiguous slice of a stream, represented by \p iovec. |
| * For the reader(s), the slice is initialized and has read-only access. |
| * For the writer, the slice is uninitialized and has read/write access. |
| * It is permitted to call obtain() multiple times without an intervening release(). |
| * Each call resets the notion of most recently obtained slice. |
| * |
| * \param iovec Non-NULL pointer to a pair of fragment descriptors. |
| * On entry, the descriptors may be uninitialized. |
| * On exit, the descriptors are initialized and refer to each of the two fragments. |
| * iovec[0] describes the initial fragment of the slice, and |
| * iovec[1] describes the remaining non-virtually-contiguous fragment. |
| * Empty iovec[0] implies that iovec[1] is also empty. |
| * iovec[0].mOffset and iovec[1].mOffset are always < capacity. |
| * Typically iovec[1].mOffset is zero, but don't assume that. |
| * \param count The maximum number of frames to obtain. |
| * See setHysteresis() for something which is close to, but not the same as, |
| * a minimum. |
| * \param timeout Indicates the maximum time to block for at least one frame. |
| * NULL and {0, 0} both mean non-blocking. |
| * Time is expressed as relative CLOCK_MONOTONIC. |
| * As an optimization, if \p timeout->tv_sec is the maximum positive value for |
| * time_t (LONG_MAX), then the implementation treats it as infinite timeout. |
| * See fifo_index.h for explanation of why representation is struct timespec. |
| * |
| * \return Actual number of frames available, if greater than or equal to zero. |
| * Guaranteed to be <= \p count and == iovec[0].mLength + iovec[1].mLength. |
| * For a reader this is also guaranteed to be <= capacity. |
| * For a writer this is also guaranteed to be <= effective buffer size, |
| * even if there is no reader that throttles writer. |
| * |
| * \retval -EIO corrupted indices, no recovery is possible |
| * \retval -EOVERFLOW reader doesn't throttle writer, and frames were lost because reader |
| * isn't keeping up with writer; see \p lost |
| * \retval -ETIMEDOUT count is greater than zero, timeout is non-NULL and not {0, 0}, |
| * timeout expired, and no frames were available after the timeout. |
| * \retval -EINTR count is greater than zero, timeout is non-NULL and not {0, 0}, timeout |
| * was interrupted by a signal, and no frames were available after signal. |
| * \retval -EWOULDBLOCK count is greater than zero, timeout is non-NULL and not {0, 0}, |
| * futex wait failed due to benign race, and unable to converge after |
| * retrying. Should usually handle like -EINTR. |
| * |
| * Applications should treat all of these as equivalent to zero available frames, |
| * except they convey extra information as to the cause. |
| * After any error, both iovec[0] and iovec[1] will be empty. |
| */ |
| virtual ssize_t obtain(audio_utils_iovec iovec[2], size_t count = SIZE_MAX, |
| const struct timespec *timeout = NULL) = 0; |
| |
| /** |
| * Release access to a portion of the most recently obtained slice. |
| * It is permitted to call release() multiple times without an intervening obtain(). |
| * |
| * \param count Number of frames to release. The cumulative number of frames released must not |
| * exceed the number of frames most recently obtained. |
| * If it ever happens, then the FIFO will be marked unusable with shutdown(). |
| */ |
| virtual void release(size_t count) = 0; |
| |
| /** |
| * Determine the number of frames that could be obtained or read/written without blocking. |
| * There's an inherent race condition: the value may soon be obsolete so shouldn't be trusted. |
| * available() may be called after obtain(), but doesn't affect the number of releasable frames. |
| * The implementation unfortunately prevents the method from being marked 'const'. |
| * |
| * \return Number of available frames, if greater than or equal to zero. |
| * \retval -EIO corrupted indices, no recovery is possible |
| * \retval -EOVERFLOW reader doesn't throttle writer, and frames were lost because reader |
| * isn't keeping up with writer |
| */ |
| virtual ssize_t available() = 0; |
| |
| /** |
| * Return the capacity, or statically configured maximum frame count. |
| * |
| * \return The capacity in frames. |
| */ |
| uint32_t capacity() const |
| { return mFifo.capacity(); } |
| |
| /** |
| * Return the total number of frames released since construction. |
| * For a reader, this includes lost and flushed frames. |
| * |
| * \return Total frames released. |
| */ |
| uint64_t totalReleased() const |
| { return mTotalReleased; } |
| |
| /** Return a reference to the associated FIFO. */ |
| audio_utils_fifo& fifo() { return mFifo; } |
| |
| protected: |
| audio_utils_fifo& mFifo; |
| |
| /** Number of frames obtained at most recent obtain(), less total number of frames released. */ |
| uint32_t mObtained; |
| |
| /** Number of times to retry a futex wait that fails with EWOULDBLOCK. */ |
| static const int kRetries = 2; |
| |
| /** |
| * Total number of frames released since construction. |
| * For a reader, this includes lost and flushed frames. |
| */ |
| uint64_t mTotalReleased; |
| }; |
| |
| //////////////////////////////////////////////////////////////////////////////// |
| |
| /** |
| * Used to write to a FIFO. There should be exactly one writer per FIFO. |
| * The writer is multi-thread safe with respect to reader(s), |
| * but not with respect to multiple threads calling the writer API. |
| */ |
| class audio_utils_fifo_writer : public audio_utils_fifo_provider { |
| |
| public: |
| /** |
| * Single-process and multi-process use same constructor here, |
| * but different FIFO constructors. |
| * |
| * \param fifo Associated FIFO. Passed by reference because it must be non-NULL. |
| */ |
| explicit audio_utils_fifo_writer(audio_utils_fifo& fifo); |
| virtual ~audio_utils_fifo_writer(); |
| |
| /** |
| * Write to FIFO. Resets the number of releasable frames to zero. |
| * |
| * \param buffer Pointer to source buffer containing \p count frames of data. |
| * Pointer must be non-NULL if \p count is greater than zero. |
| * \param count Desired number of frames to write. |
| * \param timeout Indicates the maximum time to block for at least one frame. |
| * NULL and {0, 0} both mean non-blocking. |
| * Time is expressed as relative CLOCK_MONOTONIC. |
| * As an optimization, if \p timeout->tv_sec is the maximum positive value for |
| * time_t (LONG_MAX), then the implementation treats it as infinite timeout. |
| * See fifo_index.h for explanation of why representation is struct timespec. |
| * |
| * \return Actual number of frames written, if greater than or equal to zero. |
| * Guaranteed to be <= \p count. |
| * Also guaranteed to be <= effective buffer size, |
| * even if there is no reader that throttles writer. |
| * The actual transfer count may be zero if the FIFO is full, |
| * or partial if the FIFO was almost full. |
| * \retval -EIO corrupted indices, no recovery is possible |
| * \retval -ETIMEDOUT count is greater than zero, timeout is non-NULL and not {0, 0}, |
| * timeout expired, and no frames were available after the timeout. |
| * \retval -EINTR count is greater than zero, timeout is non-NULL and not {0, 0}, timeout |
| * was interrupted by a signal, and no frames were available after signal. |
| * \retval -EWOULDBLOCK count is greater than zero, timeout is non-NULL and not {0, 0}, |
| * futex wait failed due to benign race, and unable to converge after |
| * retrying. Should usually handle like -EINTR. |
| */ |
| ssize_t write(const void *buffer, size_t count, const struct timespec *timeout = NULL); |
| |
| // Implement audio_utils_fifo_provider |
| virtual ssize_t obtain(audio_utils_iovec iovec[2], size_t count = SIZE_MAX, |
| const struct timespec *timeout = NULL); |
| virtual void release(size_t count); |
| virtual ssize_t available(); |
| |
| /** |
| * Set the current effective buffer size. |
| * Any filled frames already written or released to the buffer are unaltered, and pending |
| * releasable frames from obtain() may be release()ed. However subsequent write() and obtain() |
| * will be limited such that the total filled frame count is <= the effective buffer size. |
| * The default effective buffer size is mFifo.mFrameCount. |
| * Reducing the effective buffer size may update the hysteresis levels; see getHysteresis(). |
| * |
| * \param frameCount effective buffer size in frames. Capped to range [0, mFifo.mFrameCount]. |
| */ |
| void resize(uint32_t frameCount); |
| |
| /** |
| * Get the current effective buffer size. |
| * This value is not exposed to reader(s), and so must be conveyed via an out-of-band channel. |
| * |
| * \return effective buffer size in frames |
| */ |
| uint32_t size() const; |
| |
| /** |
| * Set the hysteresis levels for the writer to wake blocked readers. |
| * Hysteresis can decrease the number of context switches between writer and a blocking reader. |
| * A non-empty write() or release() will wake readers |
| * only if the fill level was < \p armLevel before the write() or release(), |
| * and then the fill level became > \p triggerLevel afterwards. |
| * The default value for \p armLevel is mFifo.mFrameCount, which means always armed. |
| * The default value for \p triggerLevel is zero, |
| * which means every write() or release() will wake the readers. |
| * For hysteresis, \p armLevel must be <= \p triggerLevel + 1. |
| * Increasing \p armLevel will arm for wakeup, regardless of the current fill level. |
| * |
| * \param armLevel Arm for wakeup when fill level < this value. |
| * Capped to range [0, effective buffer size]. |
| * \param triggerLevel Trigger wakeup when armed and fill level > this value. |
| * Capped to range [0, effective buffer size]. |
| */ |
| void setHysteresis(uint32_t armLevel, uint32_t triggerLevel); |
| |
| /** |
| * Get the hysteresis levels for waking readers. |
| * |
| * \param armLevel Set to the current arm level in frames. |
| * \param triggerLevel Set to the current trigger level in frames. |
| */ |
| void getHysteresis(uint32_t *armLevel, uint32_t *triggerLevel) const; |
| |
| private: |
| // Accessed by writer only using ordinary operations |
| uint32_t mLocalRear; // frame index of next frame slot available to write, or write index |
| |
| // TODO make a separate class and associate with the synchronization object |
| uint32_t mArmLevel; // arm if filled < arm level before release() |
| uint32_t mTriggerLevel; // trigger if armed and filled > trigger level after release() |
| bool mIsArmed; // whether currently armed |
| |
| uint32_t mEffectiveFrames; // current effective buffer size, <= mFifo.mFrameCount |
| }; |
| |
| //////////////////////////////////////////////////////////////////////////////// |
| |
| /** |
| * Used to read from a FIFO. There can be one or more readers per FIFO, |
| * and at most one of those readers can throttle the writer. |
| * All other readers must keep up with the writer or they will lose frames. |
| * Each reader is multi-thread safe with respect to the writer and any other readers, |
| * but not with respect to multiple threads calling the reader API. |
| */ |
| class audio_utils_fifo_reader : public audio_utils_fifo_provider { |
| |
| public: |
| /** |
| * Single-process and multi-process use same constructor here, |
| * but different FIFO constructors. |
| * |
| * \param fifo Associated FIFO. Passed by reference because it must be non-NULL. |
| * \param throttlesWriter Whether this reader throttles the writer. |
| * At most one reader can specify throttlesWriter == true. |
| * A non-throttling reader does not see any data written |
| * prior to construction of the reader. |
| * \param flush Whether to flush (discard) the entire buffer on -EOVERFLOW. |
| * The advantage of flushing is that it increases the chance that next |
| * read will be successful. The disadvantage is that it loses more data. |
| */ |
| explicit audio_utils_fifo_reader(audio_utils_fifo& fifo, bool throttlesWriter = true, |
| bool flush = false); |
| virtual ~audio_utils_fifo_reader(); |
| |
| /** |
| * Read from FIFO. Resets the number of releasable frames to zero. |
| * |
| * \param buffer Pointer to destination buffer to be filled with up to \p count frames of data. |
| * Pointer must be non-NULL if \p count is greater than zero. |
| * \param count Desired number of frames to read. |
| * \param timeout Indicates the maximum time to block for at least one frame. |
| * NULL and {0, 0} both mean non-blocking. |
| * Time is expressed as relative CLOCK_MONOTONIC. |
| * As an optimization, if \p timeout->tv_sec is the maximum positive value for |
| * time_t (LONG_MAX), then the implementation treats it as infinite timeout. |
| * See fifo_index.h for explanation of why representation is struct timespec. |
| * \param lost If non-NULL, set to the approximate number of frames lost before |
| * re-synchronization when -EOVERFLOW occurs, or set to zero when no frames lost. |
| * |
| * \return Actual number of frames read, if greater than or equal to zero. |
| * Guaranteed to be <= \p count. |
| * Also guaranteed to be <= capacity. |
| * The actual transfer count may be zero if the FIFO is empty, |
| * or partial if the FIFO was almost empty. |
| * \retval -EIO corrupted indices, no recovery is possible |
| * \retval -EOVERFLOW reader doesn't throttle writer, and frames were lost because reader |
| * isn't keeping up with writer; see \p lost |
| * \retval -ETIMEDOUT count is greater than zero, timeout is non-NULL and not {0, 0}, |
| * timeout expired, and no frames were available after the timeout. |
| * \retval -EINTR count is greater than zero, timeout is non-NULL and not {0, 0}, timeout |
| * was interrupted by a signal, and no frames were available after signal. |
| * \retval -EWOULDBLOCK count is greater than zero, timeout is non-NULL and not {0, 0}, |
| * futex wait failed due to benign race, and unable to converge after |
| * retrying. Should usually handle like -EINTR. |
| */ |
| ssize_t read(void *buffer, size_t count, const struct timespec *timeout = NULL, |
| size_t *lost = NULL); |
| |
| // Implement audio_utils_fifo_provider |
| virtual ssize_t obtain(audio_utils_iovec iovec[2], size_t count = SIZE_MAX, |
| const struct timespec *timeout = NULL); |
| virtual void release(size_t count); |
| virtual ssize_t available(); |
| |
| /** |
| * Same as audio_utils_fifo_provider::obtain, except has an additional parameter \p lost. |
| * |
| * \param iovec See audio_utils_fifo_provider::obtain. |
| * \param count See audio_utils_fifo_provider::obtain. |
| * \param timeout See audio_utils_fifo_provider::obtain. |
| * \param lost If non-NULL, set to the approximate number of frames lost before |
| * re-synchronization when -EOVERFLOW occurs, or set to zero when no frames lost. |
| * \return See audio_utils_fifo_provider::obtain for 'Returns' and 'Return values'. |
| */ |
| ssize_t obtain(audio_utils_iovec iovec[2], size_t count, const struct timespec *timeout, |
| size_t *lost); |
| |
| /** |
| * Determine the number of frames that could be obtained or read without blocking. |
| * There's an inherent race condition: the value may soon be obsolete so shouldn't be trusted. |
| * available() may be called after obtain(), but doesn't affect the number of releasable frames. |
| * The implementation unfortunately prevents the method from being marked 'const'. |
| * |
| * \param lost If non-NULL, set to the approximate number of frames lost before |
| * re-synchronization when -EOVERFLOW occurs, or set to zero when no frames lost. |
| * |
| * \return Number of available frames, if greater than or equal to zero. |
| * \retval -EIO corrupted indices, no recovery is possible |
| * \retval -EOVERFLOW reader doesn't throttle writer, and frames were lost because reader |
| * isn't keeping up with writer; see \p lost |
| */ |
| ssize_t available(size_t *lost); |
| |
| /** |
| * Flush (discard) all frames that could be obtained or read without blocking. |
| * Note that flush is a method on a reader, so if the writer wants to flush |
| * then it must communicate the request to the reader(s) via an out-of-band channel. |
| * |
| * \param lost If non-NULL, set to the approximate number of frames lost before |
| * re-synchronization when -EOVERFLOW occurs, or set to zero when no frames lost. |
| * |
| * \return Number of flushed frames, if greater than or equal to zero. |
| * This number does not include any lost frames. |
| * \retval -EIO corrupted indices, no recovery is possible |
| * \retval -EOVERFLOW reader doesn't throttle writer, and frames were lost because reader |
| * isn't keeping up with writer; see \p lost |
| */ |
| ssize_t flush(size_t *lost = NULL); |
| |
| /** |
| * Set the hysteresis levels for a throttling reader to wake a blocked writer. |
| * Hysteresis can decrease the number of context switches between reader and a blocking writer. |
| * A non-empty read() or release() by a throttling reader will wake the writer |
| * only if the fill level was > \p armLevel before the read() or release(), |
| * and then the fill level became < \p triggerLevel afterwards. |
| * The default value for \p armLevel is -1, which means always armed. |
| * The default value for \p triggerLevel is mFifo.mFrameCount, |
| * which means every read() or release() will wake the writer. |
| * For hysteresis, \p armLevel must be >= \p triggerLevel - 1. |
| * Decreasing \p armLevel will arm for wakeup, regardless of the current fill level. |
| * Note that the throttling reader is not directly aware of the writer's effective buffer size, |
| * so any change in effective buffer size must be communicated indirectly. |
| * |
| * \param armLevel Arm for wakeup when fill level > this value. |
| * Capped to range [-1, mFifo.mFrameCount]. |
| * \param triggerLevel Trigger wakeup when armed and fill level < this value. |
| * Capped to range [0, mFifo.mFrameCount]. |
| */ |
| void setHysteresis(int32_t armLevel, uint32_t triggerLevel); |
| |
| /** |
| * Get the hysteresis levels for waking readers. |
| * |
| * \param armLevel Set to the current arm level in frames. |
| * \param triggerLevel Set to the current trigger level in frames. |
| */ |
| void getHysteresis(int32_t *armLevel, uint32_t *triggerLevel) const; |
| |
| /** |
| * Return the total number of lost frames since construction, due to reader not keeping up with |
| * writer. Does not include flushed frames. |
| * It is necessary to call read(), obtain(), or flush() prior to calling this method, |
| * in order to observe an increase in the total, |
| * but it is not necessary for the 'lost' parameter of those prior calls to be non-NULL. |
| * |
| * \return Total lost frames. |
| */ |
| uint64_t totalLost() const |
| { return mTotalLost; } |
| |
| /** |
| * Return the total number of flushed frames since construction. |
| * Does not include lost frames. |
| * |
| * \return Total flushed frames. |
| */ |
| uint64_t totalFlushed() const |
| { return mTotalFlushed; } |
| |
| private: |
| // Accessed by reader only using ordinary operations |
| uint32_t mLocalFront; // frame index of first frame slot available to read, or read index |
| |
| // Points to shared front index if this reader throttles writer, or NULL if we don't throttle |
| // FIXME consider making it a boolean |
| audio_utils_fifo_index* mThrottleFront; |
| |
| bool mFlush; // whether to flush the entire buffer on -EOVERFLOW |
| |
| int32_t mArmLevel; // arm if filled > arm level before release() |
| uint32_t mTriggerLevel; // trigger if armed and filled < trigger level after release() |
| bool mIsArmed; // whether currently armed |
| |
| uint64_t mTotalLost; // total lost frames, does not include flushed frames |
| uint64_t mTotalFlushed; // total flushed frames, does not include lost frames |
| }; |
| |
| #endif // !ANDROID_AUDIO_FIFO_H |
