pipe.h File Reference

A pipe that is intended for buffering data between a source, such as a socket, and a sink, such as a parser, or vice versa. More...

Functions

struct spdk_pipe * spdk_pipe_create (void *buf, uint32_t sz)
 Construct a pipe around the given memory buffer. More...
 
void spdk_pipe_destroy (struct spdk_pipe *pipe)
 Destroys the pipe. More...
 
int spdk_pipe_writer_get_buffer (struct spdk_pipe *pipe, uint32_t sz, struct iovec *iovs)
 Acquire memory from the pipe for writing. More...
 
int spdk_pipe_writer_advance (struct spdk_pipe *pipe, uint32_t count)
 Advance the write pointer by the given number of bytes. More...
 
uint32_t spdk_pipe_reader_bytes_available (struct spdk_pipe *pipe)
 Get the number of bytes available to read from the pipe. More...
 
int spdk_pipe_reader_get_buffer (struct spdk_pipe *pipe, uint32_t sz, struct iovec *iovs)
 Obtain previously written memory from the pipe for reading. More...
 
int spdk_pipe_reader_advance (struct spdk_pipe *pipe, uint32_t count)
 Mark memory as read, making it available for writing. More...
 

Detailed Description

A pipe that is intended for buffering data between a source, such as a socket, and a sink, such as a parser, or vice versa.

Any time data is received in units that differ from the the units it is consumed in may benefit from using a pipe.

The pipe is not thread safe. Only a single thread can act as both the producer (called the writer) and the consumer (called the reader).

Function Documentation

◆ spdk_pipe_create()

struct spdk_pipe* spdk_pipe_create ( void *  buf,
uint32_t  sz 
)

Construct a pipe around the given memory buffer.

The pipe treats the memory buffer as a circular ring of bytes.

The available size for writing will be one less byte than provided. A single byte must be reserved to distinguish queue full from queue empty conditions.

Parameters
bufThe data buffer that backs this pipe.
szThe size of the data buffer.
Returns
spdk_pipe. The new pipe.

◆ spdk_pipe_destroy()

void spdk_pipe_destroy ( struct spdk_pipe *  pipe)

Destroys the pipe.

This does not release the buffer, but does make it safe for the user to release the buffer.

Parameters
pipeThe pipe to operate on.

◆ spdk_pipe_reader_advance()

int spdk_pipe_reader_advance ( struct spdk_pipe *  pipe,
uint32_t  count 
)

Mark memory as read, making it available for writing.

The user is not required to advance the same number of byte as was obtained by a previous call to spdk_pipe_reader_get_buffer().

Parameters
pipeThe pipe to operate on.
countThe number of bytes to advance.
Returns
On error, a negated errno. On success, 0.

◆ spdk_pipe_reader_bytes_available()

uint32_t spdk_pipe_reader_bytes_available ( struct spdk_pipe *  pipe)

Get the number of bytes available to read from the pipe.

Parameters
pipeThe pipe to operate on.
Returns
The number of bytes available for reading.

◆ spdk_pipe_reader_get_buffer()

int spdk_pipe_reader_get_buffer ( struct spdk_pipe *  pipe,
uint32_t  sz,
struct iovec *  iovs 
)

Obtain previously written memory from the pipe for reading.

This call populates the two element iovec provided with a region of memory containing the next available data in the pipe. The size will be up to sz bytes, but may be less.

Calling this function does not mark the memory as consumed. Calling this function twice without a call to spdk_pipe_reader_advance in between will return the same region of memory.

Parameters
pipeThe pipe to operate on.
szThe size requested.
iovsA two element iovec array that will be populated with the requested memory.
Returns
On error, a negated errno. On success, the total number of bytes available.

◆ spdk_pipe_writer_advance()

int spdk_pipe_writer_advance ( struct spdk_pipe *  pipe,
uint32_t  count 
)

Advance the write pointer by the given number of bytes.

The user can obtain memory from the pipe using spdk_pipe_writer_get_buffer(), but only calling this function marks it as consumed. The user is not required to advance the same number of bytes as was obtained from spdk_pipe_writer_get_buffer(). However, upon calling this function, the previous memory region is considered invalid and the user must call spdk_pipe_writer_get_buffer() again to obtain additional memory.

The user cannot advance past the current read location.

Parameters
pipeThe pipe to operate on.
countThe number of bytes to advance.
Returns
On error, a negated errno. On success, 0.

◆ spdk_pipe_writer_get_buffer()

int spdk_pipe_writer_get_buffer ( struct spdk_pipe *  pipe,
uint32_t  sz,
struct iovec *  iovs 
)

Acquire memory from the pipe for writing.

This function will acquire up to sz bytes from the pipe to be used for writing. It may return fewer total bytes.

The memory is only marked as consumed upon a call to spdk_pipe_writer_advance(). Multiple calls to this function without calling advance return the same region of memory.

Parameters
pipeThe pipe to operate on.
szThe size requested.
iovsA two element iovec array that will be populated with the requested memory.
Returns
The total bytes obtained. May be 0.