MPD: AsyncInputStream Class Reference

MPD 0.20.15

Public Member Functions | Protected Member Functions | Protected Attributes
AsyncInputStream Class Referenceabstract

Helper class for moving asynchronous (non-blocking) InputStream implementations to the I/O thread. More...

`#include <AsyncInputStream.hxx>`

Inheritance diagram for AsyncInputStream:
[legend]
Collaboration diagram for AsyncInputStream:
[legend]

## Public Member Functions
| AsyncInputStream (const char *_url, Mutex &_mutex, Cond &_cond, size_t _buffer_size, size_t _resume_at)
virtual | ~AsyncInputStream ()
void | Check () final
| Check for errors that may have occurred in the I/O thread. More...
bool | IsEOF () noexcept final
| Returns true if the stream has reached end-of-file. More...
void | Seek (offset_type new_offset) final
| Seeks to the specified position in the stream. More...
Tag * | ReadTag () final
| Reads the tag from the stream. More...
bool | IsAvailable () noexcept final
| Returns true if the next read operation will not block: either data is available, or end-of-stream has been reached, or an error has occurred. More...
size_t | Read (void *ptr, size_t read_size) final
| Reads data from the stream into the caller-supplied buffer. More...
Public Member Functions inherited from InputStream
| InputStream (const char *_uri, Mutex &_mutex, Cond &_cond)
virtual | ~InputStream ()
| Close the input stream and free resources. More...
const char * | GetURI () const
| The absolute URI which was used to open this stream. More...
void | Lock ()
void | Unlock ()
virtual void | Update ()
| Update the public attributes. More...
void | SetReady ()
bool | IsReady () const
| Return whether the stream is ready for reading and whether the other attributes in this struct are valid. More...
void | WaitReady ()
void | LockWaitReady ()
| Wrapper for WaitReady() which locks and unlocks the mutex; the caller must not be holding it already. More...
gcc_pure bool | HasMimeType () const noexcept
gcc_pure const char * | GetMimeType () const noexcept
void | ClearMimeType () noexcept
gcc_nonnull_all void | SetMimeType (const char *_mime)
void | SetMimeType (std::string &&_mime)
gcc_pure bool | KnownSize () const noexcept
gcc_pure offset_type | GetSize () const noexcept
void | AddOffset (offset_type delta) noexcept
gcc_pure offset_type | GetOffset () const noexcept
gcc_pure offset_type | GetRest () const noexcept
gcc_pure bool | IsSeekable () const noexcept
gcc_pure bool | CheapSeeking () const noexcept
| Determines whether seeking is cheap. More...
void | LockSeek (offset_type offset)
| Wrapper for Seek() which locks and unlocks the mutex; the caller must not be holding it already. More...
void | Rewind ()
| Rewind to the beginning of the stream. More...
void | LockRewind ()
void | Skip (offset_type _offset)
| Skip input bytes. More...
void | LockSkip (offset_type _offset)
gcc_pure bool | LockIsEOF () noexcept
| Wrapper for IsEOF() which locks and unlocks the mutex; the caller must not be holding it already. More...
gcc_malloc Tag * | LockReadTag ()
| Wrapper for ReadTag() which locks and unlocks the mutex; the caller must not be holding it already. More...
gcc_nonnull_all size_t | LockRead (void *ptr, size_t size)
| Wrapper for Read() which locks and unlocks the mutex; the caller must not be holding it already. More...
gcc_nonnull_all void | ReadFull (void *ptr, size_t size)
| Reads the whole data from the stream into the caller-supplied buffer. More...
gcc_nonnull_all void | LockReadFull (void *ptr, size_t size)
| Wrapper for ReadFull() which locks and unlocks the mutex; the caller must not be holding it already. More...

## Protected Member Functions
void | SetTag (Tag *_tag) noexcept
| Pass an tag from the I/O thread to the client thread. More...
void | ClearTag () noexcept
void | Pause () noexcept
bool | IsPaused () const noexcept
void | SetClosed () noexcept
| Declare that the underlying stream was closed. More...
bool | IsBufferEmpty () const noexcept
bool | IsBufferFull () const noexcept
gcc_pure size_t | GetBufferSpace () const noexcept
| Determine how many bytes can be added to the buffer. More...
CircularBuffer< uint8_t >::Range | PrepareWriteBuffer () noexcept
void | CommitWriteBuffer (size_t nbytes) noexcept
void | AppendToBuffer (const void *data, size_t append_size) noexcept
| Append data to the buffer. More...
virtual void | DoResume ()=0
| Implement code here that will resume the stream after it has been paused due to full input buffer. More...
virtual void | DoSeek (offset_type new_offset)=0
| The actual Seek() implementation. More...
bool | IsSeekPending () const noexcept
void | SeekDone () noexcept
| Call this after seeking has finished. More...

## Protected Attributes
std::exception_ptr | postponed_exception
Protected Attributes inherited from InputStream
bool | ready
| indicates whether the stream is ready for reading and whether the other attributes in this struct are valid More...
bool | seekable
| if true, then the stream is fully seekable More...
offset_type | size
| the size of the resource, or UNKNOWN_SIZE if unknown More...
offset_type | offset
| the current offset within the stream More...

## Additional Inherited Members
Public Types inherited from InputStream
typedef ::offset_type | offset_type
Static Public Member Functions inherited from InputStream
static gcc_nonnull_all InputStreamPtr | Open (const char *uri, Mutex &mutex, Cond &cond)
| Opens a new input stream. More...
static gcc_nonnull_all InputStreamPtr | OpenReady (const char *uri, Mutex &mutex, Cond &cond)
| Just like Open(), but waits for the stream to become ready. More...
Data Fields inherited from InputStream
Mutex & | mutex
| A mutex that protects the mutable attributes of this object and its implementation. More...
Cond & | cond
| A cond that gets signalled when the state of this object changes from the I/O thread. More...
Static Protected Attributes inherited from InputStream
static constexpr offset_type | UNKNOWN_SIZE = -1

## Detailed Description

Helper class for moving asynchronous (non-blocking) InputStream implementations to the I/O thread.

Data is being read into a ring buffer, and that buffer is then consumed by another thread using the regular InputStream API.

Definition at line 36 of file AsyncInputStream.hxx.

## Constructor & Destructor Documentation

## ◆ AsyncInputStream()

AsyncInputStream::AsyncInputStream | ( | const char * | _url,
|  | Mutex & | _mutex,
|  | Cond & | _cond,
|  | size_t | _buffer_size,
|  | size_t | _resume_at
| ) |  |

Parameters

  _buffer | a buffer allocated with HugeAllocate(); the destructor will free it using HugeFree()

## ◆ ~AsyncInputStream()

virtual AsyncInputStream::~AsyncInputStream | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ AppendToBuffer()

void AsyncInputStream::AppendToBuffer | ( | const void * | data,
|  | size_t | append_size
| ) |  |
| protectednoexcept

Append data to the buffer.

The size must fit into the buffer; see GetBufferSpace().

## ◆ Check()

void AsyncInputStream::Check | ( |  | ) |
| finalvirtual

Check for errors that may have occurred in the I/O thread.

Throws std::runtime_error on error.

Reimplemented from InputStream.

## ◆ ClearTag()

void AsyncInputStream::ClearTag | ( |  | ) |
| inlineprotectednoexcept

Definition at line 97 of file AsyncInputStream.hxx.

## ◆ CommitWriteBuffer()

void AsyncInputStream::CommitWriteBuffer | ( | size_t | nbytes | ) |
| protectednoexcept

## ◆ DoResume()

virtual void AsyncInputStream::DoResume | ( |  | ) |
| protectedpure virtual

Implement code here that will resume the stream after it has been paused due to full input buffer.

## ◆ DoSeek()

virtual void AsyncInputStream::DoSeek | ( | offset_type | new_offset | ) |
| protectedpure virtual

The actual Seek() implementation.

This virtual method will be called from within the I/O thread. When the operation is finished, call SeekDone() to notify the caller.

## ◆ GetBufferSpace()

gcc_pure size_t AsyncInputStream::GetBufferSpace | ( |  | ) | const
| inlineprotectednoexcept

Determine how many bytes can be added to the buffer.

Definition at line 128 of file AsyncInputStream.hxx.

## ◆ IsAvailable()

bool AsyncInputStream::IsAvailable | ( |  | ) |
| finalvirtualnoexcept

Returns true if the next read operation will not block: either data is available, or end-of-stream has been reached, or an error has occurred.

The caller must lock the mutex.

Reimplemented from InputStream.

## ◆ IsBufferEmpty()

bool AsyncInputStream::IsBufferEmpty | ( |  | ) | const
| inlineprotectednoexcept

Definition at line 116 of file AsyncInputStream.hxx.

## ◆ IsBufferFull()

bool AsyncInputStream::IsBufferFull | ( |  | ) | const
| inlineprotectednoexcept

Definition at line 120 of file AsyncInputStream.hxx.

## ◆ IsEOF()

bool AsyncInputStream::IsEOF | ( |  | ) |
| finalvirtualnoexcept

Returns true if the stream has reached end-of-file.

The caller must lock the mutex.

Implements InputStream.

## ◆ IsPaused()

bool AsyncInputStream::IsPaused | ( |  | ) | const
| inlineprotectednoexcept

Definition at line 103 of file AsyncInputStream.hxx.

## ◆ IsSeekPending()

bool AsyncInputStream::IsSeekPending | ( |  | ) | const
| inlineprotectednoexcept

Definition at line 157 of file AsyncInputStream.hxx.

## ◆ Pause()

void AsyncInputStream::Pause | ( |  | ) |
| protectednoexcept

## ◆ PrepareWriteBuffer()

CircularBuffer<uint8_t>::Range AsyncInputStream::PrepareWriteBuffer | ( |  | ) |
| inlineprotectednoexcept

Definition at line 132 of file AsyncInputStream.hxx.

## ◆ Read()

size_t AsyncInputStream::Read | ( | void * | ptr,
|  | size_t | size
| ) |  |
| finalvirtual

Reads data from the stream into the caller-supplied buffer.

Returns 0 on error or eof (check with IsEOF()).

The caller must lock the mutex.

Throws std::runtime_error on error.

Parameters

  ptr | the buffer to read into
  size | the maximum number of bytes to read

Returns
  the number of bytes read

Implements InputStream.

## ◆ ReadTag()

Tag* AsyncInputStream::ReadTag | ( |  | ) |
| finalvirtual

Reads the tag from the stream.

The caller must lock the mutex.

Returns
  a tag object which must be freed by the caller, or nullptr if the tag has not changed since the last call

Reimplemented from InputStream.

## ◆ Seek()

void AsyncInputStream::Seek | ( | offset_type | offset | ) |
| finalvirtual

Seeks to the specified position in the stream.

This will most likely fail if the "seekable" flag is false.

The caller must lock the mutex.

Throws std::runtime_error on error.

Parameters

  offset | the relative offset

Reimplemented from InputStream.

## ◆ SeekDone()

void AsyncInputStream::SeekDone | ( |  | ) |
| protectednoexcept

Call this after seeking has finished.

It will notify the client thread.

## ◆ SetClosed()

void AsyncInputStream::SetClosed | ( |  | ) |
| inlineprotectednoexcept

Declare that the underlying stream was closed.

We will continue feeding Read() calls from the buffer until it runs empty.

Definition at line 112 of file AsyncInputStream.hxx.

## ◆ SetTag()

void AsyncInputStream::SetTag | ( | Tag * | _tag | ) |
| protectednoexcept

Pass an tag from the I/O thread to the client thread.

## Field Documentation

## ◆ postponed_exception

std::exception_ptr AsyncInputStream::postponed_exception
| protected

Definition at line 69 of file AsyncInputStream.hxx.

The documentation for this class was generated from the following file:

- input/AsyncInputStream.hxx