2 * Copyright (c) 2008 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
21 /* An Xfer abstracts an active data transfer through the Amanda core.
29 /* An Xfer represents a flow of data from a source, via zero or more filters,
30 * to a destination. Sources, filters, and destinations are "transfer elements".
31 * The job of the Xfer is glue together a sequence of elements, and provide a
32 * dispatch point for messages from those elements to the caller.
34 * Xfers are not implemented as GObjects because there is no reason to subclass an
35 * Xfer or apply any of the other features that come with GObject.
38 /* The moment-to-moment state of a transfer */
40 XFER_INIT = 1, /* initializing */
41 XFER_START = 2, /* starting */
42 XFER_RUNNING = 3, /* data flowing */
43 XFER_CANCELLING = 4,/* cancellation begun */
44 XFER_CANCELLED = 5, /* all elements cancelled; draining data */
45 XFER_DONE = 6, /* data no longer flowing */
48 /* forward declarations */
58 /* The current status of this transfer. This is read-only, and
59 * must only be accessed from the main thread or with status_mutex
63 /* lock this while checking status in a thread
64 * other than the main thread */
67 /* and wait on this for status changes */
70 /* -- remaining fields are private -- */
74 /* All transfer elements for this transfer, in order from
75 * source to destination. This is initialized when the Xfer is
79 /* temporary string for a representation of this transfer */
82 /* GSource and queue for incoming messages */
83 struct XMsgSource *msg_source;
86 /* Number of active elements remaining (a.k.a. the number of
87 * XMSG_DONE messages to expect) */
88 gint num_active_elements;
91 typedef struct Xfer Xfer;
93 /* Note that all functions must be called from the main thread unless
96 /* Create a new Xfer object, which should later be freed with xfref_free.
98 * This function adds a reference to each element. The caller should
99 * unreference the elements if it does not intend to use them directly.
100 * The Xfer returned has a refcount of one.
102 * @param elements: array of pointers to transfer elements, in order from source
104 * @param nelements: length of 'elements'
105 * @returns: new Xfer object
107 Xfer *xfer_new(struct XferElement **elements, unsigned int nelements);
109 /* Increase the reference count of a transfer.
111 * @param xfer: the transfer
113 void xfer_ref(Xfer *xfer);
115 /* Decrease the reference count of a transfer, possibly freeing it. A running
116 * transfer (state neither XFER_INIT nor XFER_DONE) will not be freed.
118 * @param xfer: the transfer
120 void xfer_unref(Xfer *xfer);
122 /* Get a GSource which will produce events corresponding to messages from
123 * this transfer. This is a "peek" operation, so the reference count for the
124 * GSource is not affected. Note that the same GSource is returned on every
125 * call for a particular transfer.
127 * @returns: GSource object
129 GSource *xfer_get_source(Xfer *xfer);
131 /* Typedef for the callback to be set on the GSource returned from
134 typedef void (*XMsgCallback)(gpointer data, struct XMsg *msg, Xfer *xfer);
136 /* Queue a message for delivery via this transfer's GSource. This can
137 * be called in any thread.
139 * @param xfer: the transfer
140 * @param msg: the message to queue
142 void xfer_queue_message(Xfer *xfer, struct XMsg *msg);
144 /* Get a representation of this transfer. The string belongs to the transfer, and
145 * will be freed when the transfer is freed.
147 * @param xfer: the Xfer object
148 * @returns: statically allocated string
150 char *xfer_repr(Xfer *xfer);
152 /* Start a transfer. This function will fail with an error message if it is
153 * unable to set up the transfer (e.g., if the elements cannot be connected
156 * @param xfer: the Xfer object
158 void xfer_start(Xfer *xfer);
160 /* Abort a running transfer. This essentially tells the source to stop
161 * producing data and allows the remainder of the transfer to "drain". Thus
162 * the transfer will signal its completion "normally" some time after
163 * xfer_cancel returns. In particular, the state transitions will occur
167 * - xfer_cancel() (note state may still be XFER_RUNNING on return)
169 * - (individual elements' cancel() methods are invoked)
171 * - (data drains from the transfer)
174 * This function can be called from any thread at any time. It will return
177 * @param xfer: the Xfer object
179 void xfer_cancel(Xfer *xfer);