diff -r 5a2246f5be78 -r e7f0697814dc render_remote.h
--- a/render_remote.h	Sat Jun 07 05:18:06 2008 +0300
+++ b/render_remote.h	Sun Jun 08 21:03:23 2008 +0300
@@ -8,27 +8,45 @@
 #include "remote_node.h"
 
 /*
- * Execute a render_t operation on a remote render_node
+ * Execute a render operation on a remote render_node
  */
 
 
 #define RENDER_PORT_NAME "6159"
 
-struct remote_render_ctx;
+struct render_remote;
 
 /*
- * Execute the given render operation on the render_node at the given remote address.
- *
- * The various callback functions must all be provided.
+ * Execute the given render operation on the render_node at the given remote
+ * address, and buffer the data stream.
  *
- * cb_sent will be invoked after the request has succesfully been written, and before cb_data is called.
- * cb_data is called whenever new data has been received. See also, render_remote_set_chunk_size
- * cb_done is called after our last call to cb_data (note: see render_remote_shake)
- * cb_fail is called when an error is encountered. This can (and will) happen at any time!
+ * The various callback functions must all be provided!
  *
- * Returns NULL on error, or a handle that can be used for cancel/etc on success
+ * cb_sent
+ *  Will be invoked once we have a pretty good guess that the render will
+ *  complete succesfully.
+ *
+ * cb_data
+ *  Will be invoked after cb_sent has been called whenever any new data has
+ *  been received into our buffer, once we've buffered all the data, or after
+ *  render_remote_flush.
+ *
+ * cb_done
+ *  The request was terminated succesfully and all data has been read out of
+ *  our buffer by cb_data
+ *
+ * cb_fail 
+ *  The request was terminated abnormally. This may happen at any time, except
+ *  after cb_done has been called.
+ *
+ * The returned struct render_remote can be used as a handle for the control
+ * functions, and it is the caller's responsibility to free it using
+ * render_remote_free after cb_done/cb_fail has been called, or alternatively,
+ * cancel it using render_remote_cancel.
+ *
+ * Returns NULL on error, or a handle on success
  */
-struct remote_render_ctx *render_remote (
+struct render_remote *render_remote (
         struct render *render,              // what to render
         struct remote_node *remote_node,    // what render node to use
         void (*cb_sent)(void *arg),
@@ -39,10 +57,29 @@
 );
 
 /*
- * Cancel the given request. No more callbacks will be called, buffered data is
- * discarded and the remote render process will cancel ASAP.
+ * Execute the given render operation on the render_node at the given remote
+ * address, and let the user handle the read I/O events.
+ *
+ * The various callback functions must all be provided!
+ *
+ * cb_sent
+ *  Will be called once the request has been sent.
+ *
+ * cb_fail
+ *  Will be called if sending the request fails.
+ *
+ * cb_io_data
+ *  Will be called once when there is data on the socket to receive. Must be
+ *  re-enabled using render_remote_again each time.
  */
-void render_remote_cancel (struct remote_render_ctx *ctx);
+struct render_remote *render_remote_rawio (
+        struct render *render,
+        struct remote_node *remote_node,
+        void (*cb_sent)(void *arg),
+        void (*cb_fail)(void *arg),
+        void (*cb_io_data)(evutil_socket_t, short, void*),
+        void *cb_arg
+);
 
 /*
  * Controls the behaviour of when cb_data is called, and how remote data is read in.
@@ -59,20 +96,40 @@
  * called any more.
  *
  * This means that there is a potential for deadlock if the buffer is full. You
- * MUST call render_remote_shake once you are ready to start consuming the
+ * MUST call render_remote_again once you are ready to start consuming the
  * buffer again.
  *
- * Only call this once cb_sent has fired
+ * Only valid for normal buffered renders.
  */
-int render_remote_set_recv (struct remote_render_ctx *ctx, size_t recv_threshold, size_t unread_buffer);
+void render_remote_set_recv (struct render_remote *ctx, size_t recv_threshold, size_t unread_buffer);
 
 /*
- * Call cb_data with the current set of buffered input data immediately,
- * regardless of whether or not the buffer contains any data, or any new
- * data has been received.
+ * For buffered I/O, call cb_data with the current set of buffered input data
+ * immediately, regardless of whether or not the buffer contains any data, or
+ * any new data has been received. Only call this once cb_sent has been invoked.
+ */
+void render_remote_flush (struct render_remote *ctx);
+
+/*
+ * For non-buffered I/O, reschedule the cb_io_data event to be called when more
+ * data is received.
+ */
+int render_remote_reschedule (struct render_remote *ctx);
+
+/*
+ * Cancel the given request. No more callbacks will be called, the ctx is freed
+ * and the remote render process will cancel ASAP.
  *
- * Only call this after cb_sent and before cb_done/cb_fail.
+ * For buffered I/O, the any buffered data is discarded.
+ *
+ * Note that you do not need to call render_remote_free after this.
  */
-int render_remote_shake (struct remote_render_ctx *ctx);
+void render_remote_cancel (struct render_remote *ctx);
+
+/*
+ * Free the render_remote ctx and its assoicated resources. Only valid after a
+ * cb_done/cb_fail, otherwise use render_remote_cancel.
+ */
+void render_remote_free (struct render_remote *ctx);
 
 #endif /* RENDER_REMOTE_H */