#ifndef RENDER_REMOTE_H
#define RENDER_REMOTE_H

#include <event2/util.h>
#include <event2/buffer.h>

#include "render.h"
#include "remote_pool.h"

/*
 * Execute a render operation on a remote render_node
 */

struct render_remote;

/*
 * Execute the given render operation on the render_node at the given remote
 * address, and buffer the data stream.
 *
 * The various callback functions must all be provided!
 *
 * 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 render_remote *render_remote (
        struct render *render,              // what to render
        struct remote_pool *pool_info,      // pick a render node from this pool
        void (*cb_sent)(void *arg),
        void (*cb_data)(struct evbuffer *buf, void *arg),
        void (*cb_done)(void *arg),
        void (*cb_fail)(void *arg),
        void *cb_arg
);

/*
 * 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.
 */
struct render_remote *render_remote_rawio (
        struct render *render,
        struct remote_pool *pool_info, 
        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.
 *
 * recv_threshold sets a threshold for calling cb_data - cb_data will only be
 * called if the buffer contains at least recv_threshold bytes. Note that
 * cb_data is only called once new data has been receieved from the remote end.
 * If cb_data doesn't drain the buffer, cb_data will be called again once more
 * data has been received from the remote end.
 *
 * unread_buffer can be used to control the amount of unread data in cb_data.
 * If the buffer contains more than recv_threshold + unread_buffer bytes, we
 * will stop accepting bytes from the remote end, and cb_data will not be
 * called any more.
 *
 * This means that there is a potential for deadlock if the buffer is full. You
 * MUST call render_remote_again once you are ready to start consuming the
 * buffer again.
 *
 * Only valid for normal buffered renders.
 */
void render_remote_set_recv (struct render_remote *ctx, size_t recv_threshold, size_t unread_buffer);

/*
 * 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.
 *
 * For buffered I/O, the any buffered data is discarded.
 *
 * Note that you do not need to call render_remote_free after this.
 */
void render_remote_cancel (struct render_remote *ctx);

/*
 * Mark a non-buffered custom-I/O request as succesfully completed. This will
 * also free the given ctx.
 */
void render_remote_done (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 */