X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=xfer-src%2Fxfer.h;h=3d6773a02f969d3684ce91f64282c177747d3389;hb=deb1d6847fe421fbab7d1ede23b5a1d8c83027a4;hp=ca265a54d14a58c88c4b1f64feeb6e237fa82c34;hpb=2627875b7d18858bc1f9f7652811e4d8c15a23eb;p=debian%2Famanda

diff --git a/xfer-src/xfer.h b/xfer-src/xfer.h
index ca265a5..3d6773a 100644
--- a/xfer-src/xfer.h
+++ b/xfer-src/xfer.h
@@ -1,20 +1,20 @@
 /*
- * Copyright (c) 2008 Zmanda, Inc.  All Rights Reserved.
+ * Copyright (c) 2008, 2009, 2010 Zmanda, Inc.  All Rights Reserved.
  *
- * This library is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License version 2.1 as
- * published by the Free Software Foundation.
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 as published
+ * by the Free Software Foundation.
  *
- * This library is distributed in the hope that it will be useful, but
+ * This program is distributed in the hope that it will be useful, but
  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
- * License for more details.
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * for more details.
  *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this library; if not, write to the Free Software Foundation,
- * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA.
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  *
- * Contact information: Zmanda Inc., 505 N Mathlida Ave, Suite 120
+ * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  */
 
@@ -86,6 +86,10 @@ struct Xfer {
     /* Number of active elements remaining (a.k.a. the number of
      * XMSG_DONE messages to expect) */
     gint num_active_elements;
+
+    /* Used to coordinate handing off file descriptors among elements of this
+     * xfer */
+    GMutex *fd_mutex;
 };
 
 typedef struct Xfer Xfer;
@@ -154,8 +158,10 @@ char *xfer_repr(Xfer *xfer);
  * correctly).
  *
  * @param xfer: the Xfer object
+ * @param offset: the offset to start the transfer from (must be 0)
+ * @param size: the Xfer object: the number of bytes to transfer.
  */
-void xfer_start(Xfer *xfer);
+void xfer_start(Xfer *xfer, gint64 offset, gint64 size);
 
 /* Abort a running transfer.  This essentially tells the source to stop
  * producing data and allows the remainder of the transfer to "drain".  Thus
@@ -178,4 +184,53 @@ void xfer_start(Xfer *xfer);
  */
 void xfer_cancel(Xfer *xfer);
 
+/*
+ * Utilities
+ */
+
+/* Wait for the xfer's state to become CANCELLED or DONE; this is useful to
+ * wait until a cancelletion is in progress before returning an EOF or
+ * otherwise handling a failure.  If you call this in the main thread, you'll
+ * be waiting for a while.
+ *
+ * @param xfer: the transfer object
+ * @returns: the new status (XFER_CANCELLED or XFER_DONE)
+ */
+xfer_status wait_until_xfer_cancelled(Xfer *xfer);
+
+/* Wait for the xfer's state to become anything but START; this is
+ * called *automatically* for every xfer_element_pull_buffer call, as the
+ * upstream element may not be running and ready for a pull just yet.  But
+ * the function may be useful in other places, too.
+ *
+ * @param xfer: the transfer object
+ * @returns: the new status (XFER_CANCELLED or XFER_DONE)
+ */
+xfer_status wait_until_xfer_running(Xfer *xfer);
+
+/* Send an XMSG_ERROR constructed with the given format and arguments, then
+ * cancel the transfer, then wait until the transfer is completely cancelled.
+ * This is the most common error-handling process for transfer elements.  All
+ * that remains to be done on return is to branch to the appropriate point in
+ * the cancellation-handling portion of the transfer.
+ *
+ * @param elt: the transfer element producing the error
+ * @param fmt: the format for the error message
+ * @param ...: arguments corresponding to the format
+ */
+void xfer_cancel_with_error(struct XferElement *elt, const char *fmt, ...)
+	G_GNUC_PRINTF(2,3);
+
+/* Return the fd in *FDP and set *FDP to NEWFD, all in one step.  The operation
+ * is atomic with respect to all other such operations in this transfer, making
+ * this a good way to "move" a file descriptor from one element to another.  If
+ * xfer is NULL, the operation proceeds with no locking.
+ *
+ * @param xfer: the xfer within which this fd is used
+ * @param fdp: pointer to the file descriptor to swap
+ * @param newfd: the new value for *FDP
+ * @returns: the previous contents of *fdp (may be -1)
+ */
+gint xfer_atomic_swap_fd(Xfer *xfer, gint *fdp, gint newfd);
+
 #endif /* XFER_H */