2 * util/tube.h - pipe service
4 * Copyright (c) 2008, NLnet Labs. All rights reserved.
6 * This software is open source.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
15 * Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
19 * Neither the name of the NLNET LABS nor the names of its contributors may
20 * be used to endorse or promote products derived from this software without
21 * specific prior written permission.
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 * This file contains pipe service functions.
50 #include "util/locks.h"
54 * Callback from pipe listen function
55 * void mycallback(tube, msg, len, error, user_argument);
56 * if error is true (NETEVENT_*), msg is probably NULL.
58 typedef void tube_callback_type(struct tube*, uint8_t*, size_t, int, void*);
65 /** pipe end to read from */
67 /** pipe end to write on */
70 /** listen commpoint */
71 struct comm_point* listen_com;
72 /** listen callback */
73 tube_callback_type* listen_cb;
74 /** listen callback user arg */
76 /** are we currently reading a command, 0 if not, else bytecount */
78 /** size of current read command, may be partially read */
80 /** the current read command content, malloced, can be partially read*/
83 /** background write queue, commpoint to write results back */
84 struct comm_point* res_com;
85 /** are we currently writing a result, 0 if not, else bytecount into
86 * the res_list first entry. */
88 /** list of outstanding results to be written back */
89 struct tube_res_list* res_list;
91 struct tube_res_list* res_last;
93 #else /* USE_WINSOCK */
94 /** listen callback */
95 tube_callback_type* listen_cb;
96 /** listen callback user arg */
98 /** the windows sockets event (signaled if items in pipe) */
100 /** winsock event storage when registered with event base */
101 struct ub_event* ev_listen;
103 /** lock on the list of outstanding items */
104 lock_basic_type res_lock;
105 /** list of outstanding results on pipe */
106 struct tube_res_list* res_list;
108 struct tube_res_list* res_last;
109 #endif /* USE_WINSOCK */
113 * List of results (arbitrary command serializations) to write back
115 struct tube_res_list {
117 struct tube_res_list* next;
118 /** serialized buffer to write */
120 /** length to write */
126 * @return: new tube struct or NULL on error.
128 struct tube* tube_create(void);
131 * Delete and destroy a pipe
132 * @param tube: to delete
134 void tube_delete(struct tube* tube);
137 * Write length bytes followed by message.
138 * @param tube: the tube to write on.
139 * If that tube is a pipe, its write fd is used as
140 * the socket to write on. Is nonblocking.
141 * Set to blocking by the function,
142 * and back to non-blocking at exit of function.
143 * @param buf: the message.
144 * @param len: length of message.
145 * @param nonblock: if set to true, the first write is nonblocking.
146 * If the first write fails the function returns -1.
147 * If set false, the first write is blocking.
148 * @return: all remainder writes are nonblocking.
149 * return 0 on error, in that case blocking/nonblocking of socket is
151 * return 1 if all OK.
153 int tube_write_msg(struct tube* tube, uint8_t* buf, uint32_t len,
157 * Read length bytes followed by message.
158 * @param tube: The tube to read on.
159 * If that tube is a pipe, its read fd is used as
160 * the socket to read on. Is nonblocking.
161 * Set to blocking by the function,
162 * and back to non-blocking at exit of function.
163 * @param buf: the message, malloced.
164 * @param len: length of message, returned.
165 * @param nonblock: if set to true, the first read is nonblocking.
166 * If the first read fails the function returns -1.
167 * If set false, the first read is blocking.
168 * @return: all remainder reads are nonblocking.
169 * return 0 on error, in that case blocking/nonblocking of socket is
170 * unknown. On EOF 0 is returned.
171 * return 1 if all OK.
173 int tube_read_msg(struct tube* tube, uint8_t** buf, uint32_t* len,
177 * Close read part of the pipe.
178 * The tube can no longer be read from.
179 * @param tube: tube to operate on.
181 void tube_close_read(struct tube* tube);
184 * Close write part of the pipe.
185 * The tube can no longer be written to.
186 * @param tube: tube to operate on.
188 void tube_close_write(struct tube* tube);
191 * See if data is ready for reading on the tube without blocking.
192 * @param tube: tube to check for readable items
193 * @return true if readable items are present. False if not (or error).
194 * true on pipe_closed.
196 int tube_poll(struct tube* tube);
199 * Wait for data to be ready for reading on the tube. is blocking.
201 * @param tube: the tube to wait on.
202 * @return: if there was something to read (false on error).
203 * true on pipe_closed.
205 int tube_wait(struct tube* tube);
208 * Wait for data to be ready with a timeout.
209 * @param tube: the tube to wait on.
210 * @param msec: timeout in milliseconds.
211 * @return 1 if there is something to read within timeout, readability.
212 * 0 on a timeout. On failures -1, like errors. */
213 int tube_wait_timeout(struct tube* tube, int msec);
216 * Get FD that is readable when new information arrives.
218 * @return file descriptor.
220 int tube_read_fd(struct tube* tube);
223 * Start listening for information over the pipe.
224 * Background registration of a read listener, callback when read completed.
225 * Do not mix with tube_read_msg style direct reads from the pipe.
226 * @param tube: tube to listen on
227 * @param base: what base to register event callback.
228 * @param cb: callback routine.
229 * @param arg: user argument for callback routine.
230 * @return true if successful, false on error.
232 int tube_setup_bg_listen(struct tube* tube, struct comm_base* base,
233 tube_callback_type* cb, void* arg);
236 * Remove bg listen setup from event base.
237 * @param tube: what tube to cleanup
239 void tube_remove_bg_listen(struct tube* tube);
242 * Start background write handler for the pipe.
243 * Do not mix with tube_write_msg style direct writes to the pipe.
244 * @param tube: tube to write on
245 * @param base: what base to register event handler on.
246 * @return true if successful, false on error.
248 int tube_setup_bg_write(struct tube* tube, struct comm_base* base);
251 * Remove bg write setup from event base.
252 * @param tube: what tube to cleanup
254 void tube_remove_bg_write(struct tube* tube);
258 * Append data item to background list of writes.
259 * Mallocs a list entry behind the scenes.
260 * Not locked behind the scenes, call from one thread or lock on outside.
261 * @param tube: what tube to queue on.
262 * @param msg: memory message to send. Is free()d after use.
263 * Put at the end of the to-send queue.
264 * @param len: length of item.
265 * @return 0 on failure (msg freed).
267 int tube_queue_item(struct tube* tube, uint8_t* msg, size_t len);
269 /** for fptr wlist, callback function */
270 int tube_handle_listen(struct comm_point* c, void* arg, int error,
271 struct comm_reply* reply_info);
273 /** for fptr wlist, callback function */
274 int tube_handle_write(struct comm_point* c, void* arg, int error,
275 struct comm_reply* reply_info);
277 /** for fptr wlist, winsock signal event callback function */
278 void tube_handle_signal(int fd, short events, void* arg);
280 #endif /* UTIL_TUBE_H */