Loading...
Searching...
No Matches
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.
 
void * spdk_pipe_destroy (struct spdk_pipe *pipe)
 Destroys the pipe.
 
int spdk_pipe_writer_get_buffer (struct spdk_pipe *pipe, uint32_t sz, struct iovec *iovs)
 Acquire memory from the pipe for writing.
 
int spdk_pipe_writer_advance (struct spdk_pipe *pipe, uint32_t count)
 Advance the write pointer by the given number of bytes.
 
uint32_t spdk_pipe_reader_bytes_available (struct spdk_pipe *pipe)
 Get the number of bytes available to read from the pipe.
 
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.
 
int spdk_pipe_reader_advance (struct spdk_pipe *pipe, uint32_t count)
 Mark memory as read, making it available for writing.
 
struct spdk_pipe_group * spdk_pipe_group_create (void)
 Constructs a pipe group.
 
void spdk_pipe_group_destroy (struct spdk_pipe_group *group)
 Destroys the pipe group.
 
int spdk_pipe_group_add (struct spdk_pipe_group *group, struct spdk_pipe *pipe)
 Adds the pipe to the group.
 
int spdk_pipe_group_remove (struct spdk_pipe_group *group, struct spdk_pipe *pipe)
 Removes the pipe to the group.
 

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.

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.
Returns
Pipe buffer associated with the pipe when destroyed. The caller should free this buffer. It may not be the same buffer that was passed to spdk_pipe_create.

◆ spdk_pipe_group_add()

int spdk_pipe_group_add ( struct spdk_pipe_group * group,
struct spdk_pipe * pipe )

Adds the pipe to the group.

When a pipe reaches empty state, it puts the data buffer into the group's pool. If a pipe needs a data buffer, it takes one from the pool. Since the pool is a stack, a small number of data buffers tend to be re-used very frequently.

Parameters
groupThe pipe group to operate on.
pipeThe pipe to be added.
Returns
On error, a negated errno. On success, 0.

◆ spdk_pipe_group_create()

struct spdk_pipe_group * spdk_pipe_group_create ( void )

Constructs a pipe group.

Returns
spdk_pipe_group. The new pipe group.

◆ spdk_pipe_group_destroy()

void spdk_pipe_group_destroy ( struct spdk_pipe_group * group)

Destroys the pipe group.

Parameters
groupThe pipe group to operate on.

◆ spdk_pipe_group_remove()

int spdk_pipe_group_remove ( struct spdk_pipe_group * group,
struct spdk_pipe * pipe )

Removes the pipe to the group.

Parameters
groupThe pipe group to operate on.
pipeThe pipe to be removed.
Returns
On error, a negated errno. On success, 0.

◆ 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.