fix doc tpyos, rename some enums, fix printf format len for non-zero terminated strings (hg status), pass args to memcache_cmd_format_header via memcache_req_*, handle zero-length STORE requests, memcache_req is_buf_ours + free, other function name typos (keymemcache_req_key), fix req state behaviour re *_DATA_* for STORE requests and FETCH/END, better memcache_server connpool events/management, modular memcache_test with a working benchmark. This is a long commit message.
#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 */