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., 465 S Mathlida Ave, Suite 300
18 * Sunnyvale, CA 94086, 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)
35 STREAMING_REQUIREMENT_NONE,
36 STREAMING_REQUIREMENT_DESIRED,
37 STREAMING_REQUIREMENT_REQUIRED
38 } StreamingRequirement;
40 /* Valid data in this structure starts at data + offset, and has size
41 * data_size. Allocation starts at data and has size alloc_size. */
49 void free_buffer(queue_buffer_t*);
52 PRODUCER_MORE, /* Means the producer should be run again. */
53 PRODUCER_FINISHED, /* Means that no error occured, but the
54 producer should not be run again. */
55 PRODUCER_ERROR /* Means an error occured, and the producer
56 should not be run again. */
61 QUEUE_PRODUCER_ERROR = 1 << 0,
62 QUEUE_CONSUMER_ERROR = 1 << 1,
63 QUEUE_INTERNAL_ERROR = 1 << 2
66 /* The producer takes the given buffer (which is not itself NULL, but may contain
67 * a NULL data segment), and fills it with data. The producer can allocate or
68 * reallocate the buffer's 'data' element as necessary; the queueing system will
69 * free it when necessary. The result of the production operation is specified in
70 * the return value, but if the buffer is left without data, then that is
71 * interpreted as PRODUCER_ERROR. For optimal performance, the producer should
72 * supply exactly hint_size bytes of data in each call, but this is not required.
74 * The consumer is given a buffer (which will not be NULL, nor contain a NULL data
75 * segment), and is expected to process some or all of the data in that buffer. If
76 * there is a problem consuming data (such that no further data can be consumed),
77 * the consumer may return -1. Otherwise, the consumer should return the number of
78 * bytes actually consumed. If an error occurs, it should return -1, regardless
79 * of the number of bytes consumed. The queueing framework will ensure that all
80 * blocks have at least hint_size bytes, except the last. For optimal
81 * performance, the consumer should consume the entire buffer at each call, but
82 * this is not required.
84 * Note that the handling of the queue_buffer_t is different between the two
85 * functions: The producer should update queue_buffer_t as necessary to corespond
86 * to read data, while the consumer should leave the queue_buffer_t unadjusted:
87 * The queueing framework will invalidate data in the buffer according to the
88 * return value of the consumer.*/
90 typedef producer_result_t (* ProducerFunctor)(gpointer user_data,
91 queue_buffer_t* buffer,
93 typedef ssize_t (* ConsumerFunctor)(gpointer user_data,
94 queue_buffer_t* buffer);
97 /* These functions make the magic happen. The first one assumes
98 reasonable defaults, the second one provides more options.
99 % producer : A function that provides data to write.
100 % producer_user_data : A pointer to pass to that function.
101 % consumer : A function that writes data out.
102 % consumer_user_data : A pointer to pass to that function.
103 % block_size : Size of chunks to write out to consumer. If
104 nonpositive, data will be written in
105 variable-sized chunks.
106 % max_memory : Amount of memory to be used for buffering.
107 (default is DEFAULT_MAX_BUFFER_MEMORY).
108 % streaming_mode : Describes streaming mode.
109 STREAMING_REQUIREMENT_NONE: Data will be written as fast
110 as possible. No prebuffering
112 STREAMING_REQUIREMENT_DESIRED: max_memory bytes of data will
113 be prebuffered, and if the
114 buffer ever empties, no data
115 will be written until it
117 STREAMING_REQUIREMENT_REQUIRED: max_memory bytes of data will
119 thereafter data will be
120 written as fast as possible.
123 do_consumer_producer_queue(ProducerFunctor producer,
124 gpointer producer_user_data,
125 ConsumerFunctor consumer,
126 gpointer consumer_user_data);
128 do_consumer_producer_queue_full(ProducerFunctor producer,
129 gpointer producer_user_data,
130 ConsumerFunctor consumer,
131 gpointer consumer_user_data,
134 StreamingRequirement streaming_mode);
136 /* Some commonly-useful producers and consumers.*/
138 /* These functions will call read() or write() respectively. The user
139 data should be a pointer to an queue_fd_t, with fd set to the device
140 descriptor and errmsg set to NULL. */
147 queue_fd_t *queue_fd_new(int fd, char *errmsg);
148 int queue_fd_fd(queue_fd_t *queue_fd);
149 char *queue_fd_errmsg(queue_fd_t *queue_fd);
151 producer_result_t fd_read_producer(gpointer queue_fd, queue_buffer_t *buffer,
153 ssize_t fd_write_consumer(gpointer queue_fd, queue_buffer_t *buffer);
157 #endif /* QUEUEING_H */