git.gag.com Git - debian/amanda/blob - device-src/queueing.h

   1 /*
   2  * Copyright (c) 2005 Zmanda, Inc.  All Rights Reserved.
   3  *
   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.
   7  *
   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.
  12  *
  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.
  16  *
  17  * Contact information: Zmanda Inc., 505 N Mathlida Ave, Suite 120
  18  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  19  */
  20
  21 #ifndef QUEUEING_H
  22 #define QUEUEING_H
  23
  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
  27  * writes. */
  28
  29 #include <glib.h>
  30 #include "property.h"
  31
  32 #define DEFAULT_MAX_BUFFER_MEMORY (1*1024*1024)
  33
  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. */
  36 typedef struct {
  37     char *data;
  38     guint alloc_size;
  39     guint data_size;
  40     guint offset;
  41 } queue_buffer_t;
  42
  43 void free_buffer(queue_buffer_t*);
  44
  45 typedef enum {
  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. */
  51 } producer_result_t;
  52
  53 typedef enum {
  54     QUEUE_SUCCESS = 0,
  55     QUEUE_PRODUCER_ERROR = 1 << 0,
  56     QUEUE_CONSUMER_ERROR = 1 << 1,
  57     QUEUE_INTERNAL_ERROR = 1 << 2
  58 } queue_result_flags;
  59
  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,
  68  *
  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.
  78  *
  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
  84  * consumer.*/
  85 typedef producer_result_t (* ProducerFunctor)(gpointer user_data,
  86                                               queue_buffer_t* buffer,
  87                                               int hint_size);
  88 typedef int (* ConsumerFunctor)(gpointer user_data,
  89                                 queue_buffer_t* buffer);
  90
  91
  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
 106                                          will be done.
 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
 111                                          fills again.
 112          STREAMING_REQUIREMENT_REQUIRED: max_memory bytes of data will
 113                                          be prebuffered, and
 114                                          thereafter data will be
 115                                          written as fast as possible.
 116 */
 117 gboolean
 118 do_consumer_producer_queue(ProducerFunctor producer,
 119                            gpointer producer_user_data,
 120                            ConsumerFunctor consumer,
 121                            gpointer consumer_user_data);
 122 queue_result_flags
 123 do_consumer_producer_queue_full(ProducerFunctor producer,
 124                                 gpointer producer_user_data,
 125                                 ConsumerFunctor consumer,
 126                                 gpointer consumer_user_data,
 127                                 int block_size,
 128                                 size_t max_memory,
 129                                 StreamingRequirement streaming_mode);
 130
 131 /* Some commonly-useful producers and consumers.*/
 132
 133 /* These functions will call device_read_block and device_write_block
 134  * respectively. The user data should be a Device*.
 135  *
 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.
 140  */
 141 producer_result_t device_read_producer(gpointer device,
 142                                        queue_buffer_t *buffer,
 143                                        int hint_size);
 144 int device_write_consumer(gpointer device, queue_buffer_t *buffer);
 145
 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,
 149                                    int hint_size);
 150 int fd_write_consumer(gpointer fd, queue_buffer_t *buffer);
 151
 152
 153
 154 #endif /* QUEUEING_H */