diff --git a/src/common/remoteio.h b/src/common/remoteio.h
--- a/src/common/remoteio.h
+++ b/src/common/remoteio.h
@@ -22,32 +22,95 @@
 
 #include <stdlib.h>
 
-/*
-  RemoteIO provides an abstraction to the method of talking to a remote distrend. It is a layer on top of execio that should provide an equivalent interface.
+/**
+ * @file RemoteIO provides an abstraction to the method of talking to a remote distrend. It is a layer on top of execio that should provide an equivalent interface.
+ *
+ * RemoteIO works on top of multiio, so for it to work you write your
+ * program in an event-oriented fashion and call multiio_poll().
  */
 
 struct remoteio_opts;
 struct remoteio;
 
 /**
-   Opens connection with remote distrend. Returns 1 on error.
+ * asynchronous read handler signature.
+ *
+ * This is the signature of the callback that is called when data is
+ * available for reading. The handler may process as much of the
+ * available data as it wants. When it has processed a chunk of data,
+ * it must return the length of the data that it processed. If the
+ * handler returns 0, the handler is essentially signalling ``I can't
+ * figure out what this means until I see more''.
+ *
+ * If you need to close a socket after reading certain data from it,
+ * you may call remoteio_close() from inside of this function.
+ *
+ * @param rem the associated remoteio handle
+ * @param generic_data a pointer that is stored in remoteio's struct remoteio_opts which isn't client-specific
+ * @param buf a pointer to the buffer containing data waiting to be processed
+ * @param len the size of buf that may be accessed
+ * @param data the pointer passed to remoteio_open. _NOT_ the data just received on the socket.
+ * @return the number of bytes that the function accepted and thus should be removed from the rem handle.
+ */
+typedef size_t(*remoteio_read_handle_func_t)(struct remoteio *rem, void *generic_data, void *buf, size_t len, void *data);
 
-   @todo should this be asynchronous?
+/**
+ * Determines the value of generic_data which is passed to
+ * remoteio_read_handle_func_t
+ *
+ * @param opts the remoteio runtime options
  */
-int remoteio_open(struct remoteio **rem, struct remoteio_opts *opts, const char *servername);
+int remoteio_generic_data_set(struct remoteio_opts *opts, void *generic_data);
 
 /**
-   non-blocking I/O.
-   @param len must be greater than 0
+   Opens connection with to a remote distrend. Returns 1 on error.
 
-   @return 0 on success, 1 on failure. 
+   @todo should this be asynchronous? YES! but optionally, perhaps
+   @param opts the configuration settings for remoteio gotten from options_init().
+   @param read_handler the function to call when data has been read from the server.
+   @param read_handler_data the data to pass to the read_handler function.
+   @param servername the name of the configuration file entry for the server.
+   From this, information about how to make the outgoing connection is derived.
  */
-int remoteio_read(struct remoteio *rem, void *buf, size_t len, size_t *bytesread);
-int remoteio_write(struct remoteio *rem, void *buf, size_t len, size_t *byteswritten);
+int remoteio_open_server(struct remoteio **rem,
+			 struct remoteio_opts *opts,
+			 remoteio_read_handle_func_t read_handler,
+			 void *read_handler_data,
+			 const char *servername);
 
 /**
-   Closes a remoteio session.
-   @return nonzero on error
+ * Initializes a remoteio instance for a socket that's already been floating
+ * around for a while. I.e., this socket probably came from accept().
+ *
+ * @param rem a pointer to where the poiner to the newly allocated struct remoteio should be stored.
+ * @param opts remoteio's options
+ * @param read_handler the function to call when data has been read from the server.
+ * @param read_handler_data the data to pass to the read_handler function.
+ * @param opts self explanatory.
+ */
+int remoteio_open_socket(struct remoteio **rem,
+			 struct remoteio_opts *opts,
+			 remoteio_read_handle_func_t read_handler,
+			 void *read_handler_data,
+			 int fd);
+
+/**
+ * Queue bytes to be written to the remote host.
+ *
+ * @param rem the remoteio handle
+ * @param buf a buffer to be queued for writing. We will copy this, so the caller has to handle its memory (and free() it if necessary).
+ * @param len number of bytes to grab from buf
+ * @return 0 on success, 1 on failure
+ */
+int remoteio_write(struct remoteio *rem, const void *buf, size_t len);
+
+/**
+ * Closes a remoteio session.
+ *
+ * It is safe to call this function from within
+ * remoteio_read_handle_func_t.
+ *
+ * @return nonzero on error
 */
 int remoteio_close(struct remoteio *rem);