]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright (c) Intel Corporation. All rights reserved. | |
5 | * | |
6 | * Redistribution and use in source and binary forms, with or without | |
7 | * modification, are permitted provided that the following conditions | |
8 | * are met: | |
9 | * | |
10 | * * Redistributions of source code must retain the above copyright | |
11 | * notice, this list of conditions and the following disclaimer. | |
12 | * * Redistributions in binary form must reproduce the above copyright | |
13 | * notice, this list of conditions and the following disclaimer in | |
14 | * the documentation and/or other materials provided with the | |
15 | * distribution. | |
16 | * * Neither the name of Intel Corporation nor the names of its | |
17 | * contributors may be used to endorse or promote products derived | |
18 | * from this software without specific prior written permission. | |
19 | * | |
20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
21 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
22 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
23 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
24 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
25 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
26 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
27 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
28 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
29 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
30 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
31 | */ | |
32 | ||
33 | /** \file | |
34 | * A pipe that is intended for buffering data between a source, such as | |
35 | * a socket, and a sink, such as a parser, or vice versa. Any time data | |
36 | * is received in units that differ from the the units it is consumed | |
37 | * in may benefit from using a pipe. | |
38 | * | |
39 | * The pipe is not thread safe. Only a single thread can act as both | |
40 | * the producer (called the writer) and the consumer (called the reader). | |
41 | */ | |
42 | ||
43 | #ifndef SPDK_PIPE_H | |
44 | #define SPDK_PIPE_H | |
45 | ||
46 | #include "spdk/stdinc.h" | |
47 | ||
48 | struct spdk_pipe; | |
49 | ||
50 | /** | |
51 | * Construct a pipe around the given memory buffer. The pipe treats the memory | |
52 | * buffer as a circular ring of bytes. | |
53 | * | |
54 | * The available size for writing will be one less byte than provided. A single | |
55 | * byte must be reserved to distinguish queue full from queue empty conditions. | |
56 | * | |
57 | * \param buf The data buffer that backs this pipe. | |
58 | * \param sz The size of the data buffer. | |
59 | * | |
60 | * \return spdk_pipe. The new pipe. | |
61 | */ | |
62 | struct spdk_pipe *spdk_pipe_create(void *buf, uint32_t sz); | |
63 | ||
64 | /** | |
65 | * Destroys the pipe. This does not release the buffer, but does | |
66 | * make it safe for the user to release the buffer. | |
67 | * | |
68 | * \param pipe The pipe to operate on. | |
69 | */ | |
70 | void spdk_pipe_destroy(struct spdk_pipe *pipe); | |
71 | ||
72 | /** | |
73 | * Acquire memory from the pipe for writing. | |
74 | * | |
75 | * This function will acquire up to sz bytes from the pipe to be used for | |
76 | * writing. It may return fewer total bytes. | |
77 | * | |
78 | * The memory is only marked as consumed upon a call to spdk_pipe_writer_advance(). | |
79 | * Multiple calls to this function without calling advance return the same region | |
80 | * of memory. | |
81 | * | |
82 | * \param pipe The pipe to operate on. | |
83 | * \param sz The size requested. | |
84 | * \param iovs A two element iovec array that will be populated with the requested memory. | |
85 | * | |
86 | * \return The total bytes obtained. May be 0. | |
87 | */ | |
88 | int spdk_pipe_writer_get_buffer(struct spdk_pipe *pipe, uint32_t sz, struct iovec *iovs); | |
89 | ||
90 | /** | |
91 | * Advance the write pointer by the given number of bytes | |
92 | * | |
93 | * The user can obtain memory from the pipe using spdk_pipe_writer_get_buffer(), | |
94 | * but only calling this function marks it as consumed. The user is not required | |
95 | * to advance the same number of bytes as was obtained from spdk_pipe_writer_get_buffer(). | |
96 | * However, upon calling this function, the previous memory region is considered | |
97 | * invalid and the user must call spdk_pipe_writer_get_buffer() again to obtain | |
98 | * additional memory. | |
99 | * | |
100 | * The user cannot advance past the current read location. | |
101 | * | |
102 | * \param pipe The pipe to operate on. | |
103 | * \param count The number of bytes to advance. | |
104 | * | |
105 | * \return On error, a negated errno. On success, 0. | |
106 | */ | |
107 | int spdk_pipe_writer_advance(struct spdk_pipe *pipe, uint32_t count); | |
108 | ||
109 | /** | |
110 | * Get the number of bytes available to read from the pipe. | |
111 | * | |
112 | * \param pipe The pipe to operate on. | |
113 | * | |
114 | * \return The number of bytes available for reading. | |
115 | */ | |
116 | uint32_t spdk_pipe_reader_bytes_available(struct spdk_pipe *pipe); | |
117 | ||
118 | /** | |
119 | * Obtain previously written memory from the pipe for reading. | |
120 | * | |
121 | * This call populates the two element iovec provided with a region | |
122 | * of memory containing the next available data in the pipe. The size | |
123 | * will be up to sz bytes, but may be less. | |
124 | * | |
125 | * Calling this function does not mark the memory as consumed. Calling this function | |
126 | * twice without a call to spdk_pipe_reader_advance in between will return the same | |
127 | * region of memory. | |
128 | * | |
129 | * \param pipe The pipe to operate on. | |
130 | * \param sz The size requested. | |
131 | * \param iovs A two element iovec array that will be populated with the requested memory. | |
132 | * | |
133 | * \return On error, a negated errno. On success, the total number of bytes available. | |
134 | */ | |
135 | int spdk_pipe_reader_get_buffer(struct spdk_pipe *pipe, uint32_t sz, struct iovec *iovs); | |
136 | ||
137 | /** | |
138 | * Mark memory as read, making it available for writing. The user is not required | |
139 | * to advance the same number of byte as was obtained by a previous call to | |
140 | * spdk_pipe_reader_get_buffer(). | |
141 | * | |
142 | * \param pipe The pipe to operate on. | |
143 | * \param count The number of bytes to advance. | |
144 | * | |
145 | * \return On error, a negated errno. On success, 0. | |
146 | */ | |
147 | int spdk_pipe_reader_advance(struct spdk_pipe *pipe, uint32_t count); | |
148 | ||
149 | #endif |