2 * Copyright (c) 2005 Zmanda, Inc. All Rights Reserved.
4 * This library is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License version 2.1 as
6 * published by the Free Software Foundation.
8 * This library is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
11 * License for more details.
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this library; if not, write to the Free Software Foundation,
15 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
17 * Contact information: Zmanda Inc., 505 N Mathlida Ave, Suite 120
18 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
24 /* This file contains the code for fast threaded reading and writing to/from
25 * media, for devices that don't require any special handling. Some
26 * devices (e.g., CD-ROM) may use a different method for bulk reads or
32 #define DEFAULT_MAX_BUFFER_MEMORY (1*1024*1024)
34 /* Valid data in this structure starts at data + offset, and has size
35 * data_size. Allocation starts at data and has size alloc_size. */
43 void free_buffer(queue_buffer_t*);
46 PRODUCER_MORE, /* Means the producer should be run again. */
47 PRODUCER_FINISHED, /* Means that no error occured, but the
48 producer should not be run again. */
49 PRODUCER_ERROR /* Means an error occured, and the producer
50 should not be run again. */
55 QUEUE_PRODUCER_ERROR = 1 << 0,
56 QUEUE_CONSUMER_ERROR = 1 << 1,
57 QUEUE_INTERNAL_ERROR = 1 << 2
60 /* The producer takes the given buffer (which is not itself NULL, but
61 * may contain a NULL data segment), and fills it with data. The
62 * producer should feel free to allocate or reallocate data as
63 * necessary; the queueing system will free it when necessary. The
64 * result of the production operation is specified in the return
65 * value, but if the buffer is left without data, then that is
66 * interpreted as PRODUCER_ERROR. It is preferred (but not required)
67 * that the producer produce hint_size bytes of data,
69 * The consumer takes the given buffer (which will not be NULL, nor
70 * contain a NULL data segment) and processess it. If there is a
71 * problem consuming data (such that no further data should be
72 * consumed), the consumer may return -1. Otherwise, the consumer
73 * should return the number of bytes actually consumed.
74 * If an error occurs, return -1, regardless of the number of bytes consumed.
75 * If the amount of data written is not a full block, then this is the
76 * last (partial block) of data. The consumer should do whatever is
77 * appropriate in that case.
79 * Note that the handling of the queue_buffer_t is different between
80 * the two functions: The producer should update queue_buffer_t as
81 * necessary to corespond to read data, while the consumer should
82 * leave the queue_buffer_t unadjusted: The queueing framework will
83 * invalidate data in the buffer according to the return value of the
85 typedef producer_result_t (* ProducerFunctor)(gpointer user_data,
86 queue_buffer_t* buffer,
88 typedef int (* ConsumerFunctor)(gpointer user_data,
89 queue_buffer_t* buffer);
92 /* These functions make the magic happen. The first one assumes
93 reasonable defaults, the second one provides more options.
94 % producer : A function that provides data to write.
95 % producer_user_data : A pointer to pass to that function.
96 % consumer : A function that writes data out.
97 % consumer_user_data : A pointer to pass to that function.
98 % block_size : Size of chunks to write out to consumer. If
99 nonpositive, data will be written in
100 variable-sized chunks.
101 % max_memory : Amount of memory to be used for buffering.
102 (default is DEFAULT_MAX_BUFFER_MEMORY).
103 % streaming_mode : Describes streaming mode.
104 STREAMING_REQUIREMENT_NONE: Data will be written as fast
105 as possible. No prebuffering
107 STREAMING_REQUIREMENT_DESIRED: max_memory bytes of data will
108 be prebuffered, and if the
109 buffer ever empties, no data
110 will be written until it
112 STREAMING_REQUIREMENT_REQUIRED: max_memory bytes of data will
114 thereafter data will be
115 written as fast as possible.
118 do_consumer_producer_queue(ProducerFunctor producer,
119 gpointer producer_user_data,
120 ConsumerFunctor consumer,
121 gpointer consumer_user_data);
123 do_consumer_producer_queue_full(ProducerFunctor producer,
124 gpointer producer_user_data,
125 ConsumerFunctor consumer,
126 gpointer consumer_user_data,
129 StreamingRequirement streaming_mode);
131 /* Some commonly-useful producers and consumers.*/
133 /* These functions will call device_read_block and device_write_block
134 * respectively. The user data should be a Device*.
136 * device_write_consumer assumes that the block_size passed to
137 * do_consumer_producer_queue_full is at least device_write_min_size();
138 * do_consumer_thread() will not pass a buffer of less than block_size
139 * to the consumer unless it has received EOF from the producer thread.
141 producer_result_t device_read_producer(gpointer device,
142 queue_buffer_t *buffer,
144 int device_write_consumer(gpointer device, queue_buffer_t *buffer);
146 /* These functions will call read() or write() respectively. The user
147 data should be a file descriptor stored with GINT_TO_POINTER. */
148 producer_result_t fd_read_producer(gpointer fd, queue_buffer_t *buffer,
150 int fd_write_consumer(gpointer fd, queue_buffer_t *buffer);
154 #endif /* QUEUEING_H */