terom@2: #ifndef RENDER_REMOTE_H
terom@2: #define RENDER_REMOTE_H
terom@2: 
terom@4: #include <event2/util.h>
terom@4: #include <event2/buffer.h>
terom@2: 
terom@2: #include "render.h"
terom@19: #include "remote_pool.h"
terom@2: 
terom@2: /*
terom@15:  * Execute a render operation on a remote render_node
terom@2:  */
terom@2: 
terom@15: struct render_remote;
terom@3: 
terom@2: /*
terom@15:  * Execute the given render operation on the render_node at the given remote
terom@15:  * address, and buffer the data stream.
terom@3:  *
terom@15:  * The various callback functions must all be provided!
terom@11:  *
terom@15:  * cb_sent
terom@15:  *  Will be invoked once we have a pretty good guess that the render will
terom@15:  *  complete succesfully.
terom@15:  *
terom@15:  * cb_data
terom@15:  *  Will be invoked after cb_sent has been called whenever any new data has
terom@15:  *  been received into our buffer, once we've buffered all the data, or after
terom@15:  *  render_remote_flush.
terom@15:  *
terom@15:  * cb_done
terom@15:  *  The request was terminated succesfully and all data has been read out of
terom@15:  *  our buffer by cb_data
terom@15:  *
terom@15:  * cb_fail 
terom@15:  *  The request was terminated abnormally. This may happen at any time, except
terom@15:  *  after cb_done has been called.
terom@15:  *
terom@15:  * The returned struct render_remote can be used as a handle for the control
terom@15:  * functions, and it is the caller's responsibility to free it using
terom@15:  * render_remote_free after cb_done/cb_fail has been called, or alternatively,
terom@15:  * cancel it using render_remote_cancel.
terom@15:  *
terom@15:  * Returns NULL on error, or a handle on success
terom@2:  */
terom@15: struct render_remote *render_remote (
terom@11:         struct render *render,              // what to render
terom@19:         struct remote_pool *pool_info,      // pick a render node from this pool
terom@2:         void (*cb_sent)(void *arg),
terom@2:         void (*cb_data)(struct evbuffer *buf, void *arg),
terom@2:         void (*cb_done)(void *arg),
terom@2:         void (*cb_fail)(void *arg),
terom@8:         void *cb_arg
terom@2: );
terom@2: 
terom@3: /*
terom@15:  * Execute the given render operation on the render_node at the given remote
terom@15:  * address, and let the user handle the read I/O events.
terom@15:  *
terom@15:  * The various callback functions must all be provided!
terom@15:  *
terom@15:  * cb_sent
terom@15:  *  Will be called once the request has been sent.
terom@15:  *
terom@15:  * cb_fail
terom@15:  *  Will be called if sending the request fails.
terom@15:  *
terom@15:  * cb_io_data
terom@15:  *  Will be called once when there is data on the socket to receive. Must be
terom@15:  *  re-enabled using render_remote_again each time.
terom@3:  */
terom@15: struct render_remote *render_remote_rawio (
terom@15:         struct render *render,
terom@19:         struct remote_pool *pool_info, 
terom@15:         void (*cb_sent)(void *arg),
terom@15:         void (*cb_fail)(void *arg),
terom@15:         void (*cb_io_data)(evutil_socket_t, short, void*),
terom@15:         void *cb_arg
terom@15: );
terom@3: 
terom@3: /*
terom@6:  * Controls the behaviour of when cb_data is called, and how remote data is read in.
terom@3:  *
terom@7:  * recv_threshold sets a threshold for calling cb_data - cb_data will only be
terom@7:  * called if the buffer contains at least recv_threshold bytes. Note that
terom@7:  * cb_data is only called once new data has been receieved from the remote end.
terom@7:  * If cb_data doesn't drain the buffer, cb_data will be called again once more
terom@7:  * data has been received from the remote end.
terom@3:  *
terom@7:  * unread_buffer can be used to control the amount of unread data in cb_data.
terom@7:  * If the buffer contains more than recv_threshold + unread_buffer bytes, we
terom@7:  * will stop accepting bytes from the remote end, and cb_data will not be
terom@7:  * called any more.
terom@7:  *
terom@7:  * This means that there is a potential for deadlock if the buffer is full. You
terom@15:  * MUST call render_remote_again once you are ready to start consuming the
terom@7:  * buffer again.
terom@3:  *
terom@15:  * Only valid for normal buffered renders.
terom@3:  */
terom@15: void render_remote_set_recv (struct render_remote *ctx, size_t recv_threshold, size_t unread_buffer);
terom@6: 
terom@6: /*
terom@15:  * For buffered I/O, call cb_data with the current set of buffered input data
terom@15:  * immediately, regardless of whether or not the buffer contains any data, or
terom@15:  * any new data has been received. Only call this once cb_sent has been invoked.
terom@15:  */
terom@15: void render_remote_flush (struct render_remote *ctx);
terom@15: 
terom@15: /*
terom@15:  * For non-buffered I/O, reschedule the cb_io_data event to be called when more
terom@15:  * data is received.
terom@15:  */
terom@15: int render_remote_reschedule (struct render_remote *ctx);
terom@15: 
terom@15: /*
terom@15:  * Cancel the given request. No more callbacks will be called, the ctx is freed
terom@15:  * and the remote render process will cancel ASAP.
terom@6:  *
terom@15:  * For buffered I/O, the any buffered data is discarded.
terom@15:  *
terom@15:  * Note that you do not need to call render_remote_free after this.
terom@6:  */
terom@15: void render_remote_cancel (struct render_remote *ctx);
terom@15: 
terom@15: /*
terom@16:  * Mark a non-buffered custom-I/O request as succesfully completed. This will
terom@16:  * also free the given ctx.
terom@16:  */
terom@16: void render_remote_done (struct render_remote *ctx);
terom@16: 
terom@16: /*
terom@15:  * Free the render_remote ctx and its assoicated resources. Only valid after a
terom@15:  * cb_done/cb_fail, otherwise use render_remote_cancel.
terom@15:  */
terom@15: void render_remote_free (struct render_remote *ctx);
terom@3: 
terom@2: #endif /* RENDER_REMOTE_H */