1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2019 Intel Corporation. All rights reserved. 3 */ 4 5 /** \file 6 * A pipe that is intended for buffering data between a source, such as 7 * a socket, and a sink, such as a parser, or vice versa. Any time data 8 * is received in units that differ from the the units it is consumed 9 * in may benefit from using a pipe. 10 * 11 * The pipe is not thread safe. Only a single thread can act as both 12 * the producer (called the writer) and the consumer (called the reader). 13 */ 14 15 #ifndef SPDK_PIPE_H 16 #define SPDK_PIPE_H 17 18 #include "spdk/stdinc.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 struct spdk_pipe; 25 struct spdk_pipe_group; 26 27 /** 28 * Construct a pipe around the given memory buffer. The pipe treats the memory 29 * buffer as a circular ring of bytes. 30 * 31 * \param buf The data buffer that backs this pipe. 32 * \param sz The size of the data buffer. 33 * 34 * \return spdk_pipe. The new pipe. 35 */ 36 struct spdk_pipe *spdk_pipe_create(void *buf, uint32_t sz); 37 38 /** 39 * Destroys the pipe. This does not release the buffer, but does 40 * make it safe for the user to release the buffer. 41 * 42 * \param pipe The pipe to operate on. 43 * \return Pipe buffer associated with the pipe when destroyed. The 44 * caller should free this buffer. It may not be the same 45 * buffer that was passed to spdk_pipe_create. 46 */ 47 void *spdk_pipe_destroy(struct spdk_pipe *pipe); 48 49 /** 50 * Acquire memory from the pipe for writing. 51 * 52 * This function will acquire up to sz bytes from the pipe to be used for 53 * writing. It may return fewer total bytes. 54 * 55 * The memory is only marked as consumed upon a call to spdk_pipe_writer_advance(). 56 * Multiple calls to this function without calling advance return the same region 57 * of memory. 58 * 59 * \param pipe The pipe to operate on. 60 * \param sz The size requested. 61 * \param iovs A two element iovec array that will be populated with the requested memory. 62 * 63 * \return The total bytes obtained. May be 0. 64 */ 65 int spdk_pipe_writer_get_buffer(struct spdk_pipe *pipe, uint32_t sz, struct iovec *iovs); 66 67 /** 68 * Advance the write pointer by the given number of bytes 69 * 70 * The user can obtain memory from the pipe using spdk_pipe_writer_get_buffer(), 71 * but only calling this function marks it as consumed. The user is not required 72 * to advance the same number of bytes as was obtained from spdk_pipe_writer_get_buffer(). 73 * However, upon calling this function, the previous memory region is considered 74 * invalid and the user must call spdk_pipe_writer_get_buffer() again to obtain 75 * additional memory. 76 * 77 * The user cannot advance past the current read location. 78 * 79 * \param pipe The pipe to operate on. 80 * \param count The number of bytes to advance. 81 * 82 * \return On error, a negated errno. On success, 0. 83 */ 84 int spdk_pipe_writer_advance(struct spdk_pipe *pipe, uint32_t count); 85 86 /** 87 * Get the number of bytes available to read from the pipe. 88 * 89 * \param pipe The pipe to operate on. 90 * 91 * \return The number of bytes available for reading. 92 */ 93 uint32_t spdk_pipe_reader_bytes_available(struct spdk_pipe *pipe); 94 95 /** 96 * Obtain previously written memory from the pipe for reading. 97 * 98 * This call populates the two element iovec provided with a region 99 * of memory containing the next available data in the pipe. The size 100 * will be up to sz bytes, but may be less. 101 * 102 * Calling this function does not mark the memory as consumed. Calling this function 103 * twice without a call to spdk_pipe_reader_advance in between will return the same 104 * region of memory. 105 * 106 * \param pipe The pipe to operate on. 107 * \param sz The size requested. 108 * \param iovs A two element iovec array that will be populated with the requested memory. 109 * 110 * \return On error, a negated errno. On success, the total number of bytes available. 111 */ 112 int spdk_pipe_reader_get_buffer(struct spdk_pipe *pipe, uint32_t sz, struct iovec *iovs); 113 114 /** 115 * Mark memory as read, making it available for writing. The user is not required 116 * to advance the same number of byte as was obtained by a previous call to 117 * spdk_pipe_reader_get_buffer(). 118 * 119 * \param pipe The pipe to operate on. 120 * \param count The number of bytes to advance. 121 * 122 * \return On error, a negated errno. On success, 0. 123 */ 124 int spdk_pipe_reader_advance(struct spdk_pipe *pipe, uint32_t count); 125 126 /** 127 * Constructs a pipe group. 128 * 129 * \return spdk_pipe_group. The new pipe group. 130 */ 131 struct spdk_pipe_group *spdk_pipe_group_create(void); 132 133 /** 134 * Destroys the pipe group. 135 * 136 * \param group The pipe group to operate on. 137 */ 138 void spdk_pipe_group_destroy(struct spdk_pipe_group *group); 139 140 /** 141 * Adds the pipe to the group. 142 * 143 * When a pipe reaches empty state, it puts the data buffer into 144 * the group's pool. If a pipe needs a data buffer, it takes one 145 * from the pool. Since the pool is a stack, a small number of 146 * data buffers tend to be re-used very frequently. 147 * 148 * \param group The pipe group to operate on. 149 * \param pipe The pipe to be added. 150 * 151 * \return On error, a negated errno. On success, 0. 152 */ 153 int spdk_pipe_group_add(struct spdk_pipe_group *group, struct spdk_pipe *pipe); 154 155 /** 156 * Removes the pipe to the group. 157 * 158 * \param group The pipe group to operate on. 159 * \param pipe The pipe to be removed. 160 * 161 * \return On error, a negated errno. On success, 0. 162 */ 163 int spdk_pipe_group_remove(struct spdk_pipe_group *group, struct spdk_pipe *pipe); 164 165 #ifdef __cplusplus 166 } 167 #endif 168 169 #endif 170