1

#ifndef RENDER_REMOTE_H

     2

#define RENDER_REMOTE_H

     3

     4

#include <event2/util.h>

     5

#include <event2/buffer.h>

     6

     7

#include "render.h"

     8

#include "remote_pool.h"

     9

    10

/*

    11

 * Execute a render operation on a remote render_node

    12

 */

    13

    14

struct render_remote;

    15

    16

/*

    17

 * Execute the given render operation on the render_node at the given remote

    18

 * address, and buffer the data stream.

    19

 *

    20

 * The various callback functions must all be provided!

    21

 *

    22

 * cb_sent

    23

 *  Will be invoked once we have a pretty good guess that the render will

    24

 *  complete succesfully.

    25

 *

    26

 * cb_data

    27

 *  Will be invoked after cb_sent has been called whenever any new data has

    28

 *  been received into our buffer, once we've buffered all the data, or after

    29

 *  render_remote_flush.

    30

 *

    31

 * cb_done

    32

 *  The request was terminated succesfully and all data has been read out of

    33

 *  our buffer by cb_data

    34

 *

    35

 * cb_fail 

    36

 *  The request was terminated abnormally. This may happen at any time, except

    37

 *  after cb_done has been called.

    38

 *

    39

 * The returned struct render_remote can be used as a handle for the control

    40

 * functions, and it is the caller's responsibility to free it using

    41

 * render_remote_free after cb_done/cb_fail has been called, or alternatively,

    42

 * cancel it using render_remote_cancel.

    43

 *

    44

 * Returns NULL on error, or a handle on success

    45

 */

    46

struct render_remote *render_remote (

    47

        struct render *render,              // what to render

    48

        struct remote_pool *pool_info,      // pick a render node from this pool

    49

        void (*cb_sent)(void *arg),

    50

        void (*cb_data)(struct evbuffer *buf, void *arg),

    51

        void (*cb_done)(void *arg),

    52

        void (*cb_fail)(void *arg),

    53

        void *cb_arg

    54

);

    55

    56

/*

    57

 * Execute the given render operation on the render_node at the given remote

    58

 * address, and let the user handle the read I/O events.

    59

 *

    60

 * The various callback functions must all be provided!

    61

 *

    62

 * cb_sent

    63

 *  Will be called once the request has been sent.

    64

 *

    65

 * cb_fail

    66

 *  Will be called if sending the request fails.

    67

 *

    68

 * cb_io_data

    69

 *  Will be called once when there is data on the socket to receive. Must be

    70

 *  re-enabled using render_remote_again each time.

    71

 */

    72

struct render_remote *render_remote_rawio (

    73

        struct render *render,

    74

        struct remote_pool *pool_info, 

    75

        void (*cb_sent)(void *arg),

    76

        void (*cb_fail)(void *arg),

    77

        void (*cb_io_data)(evutil_socket_t, short, void*),

    78

        void *cb_arg

    79

);

    80

    81

/*

    82

 * Controls the behaviour of when cb_data is called, and how remote data is read in.

    83

 *

    84

 * recv_threshold sets a threshold for calling cb_data - cb_data will only be

    85

 * called if the buffer contains at least recv_threshold bytes. Note that

    86

 * cb_data is only called once new data has been receieved from the remote end.

    87

 * If cb_data doesn't drain the buffer, cb_data will be called again once more

    88

 * data has been received from the remote end.

    89

 *

    90

 * unread_buffer can be used to control the amount of unread data in cb_data.

    91

 * If the buffer contains more than recv_threshold + unread_buffer bytes, we

    92

 * will stop accepting bytes from the remote end, and cb_data will not be

    93

 * called any more.

    94

 *

    95

 * This means that there is a potential for deadlock if the buffer is full. You

    96

 * MUST call render_remote_again once you are ready to start consuming the

    97

 * buffer again.

    98

 *

    99

 * Only valid for normal buffered renders.

   100

 */

   101

void render_remote_set_recv (struct render_remote *ctx, size_t recv_threshold, size_t unread_buffer);

   102

   103

/*

   104

 * For buffered I/O, call cb_data with the current set of buffered input data

   105

 * immediately, regardless of whether or not the buffer contains any data, or

   106

 * any new data has been received. Only call this once cb_sent has been invoked.

   107

 */

   108

void render_remote_flush (struct render_remote *ctx);

   109

   110

/*

   111

 * For non-buffered I/O, reschedule the cb_io_data event to be called when more

   112

 * data is received.

   113

 */

   114

int render_remote_reschedule (struct render_remote *ctx);

   115

   116

/*

   117

 * Cancel the given request. No more callbacks will be called, the ctx is freed

   118

 * and the remote render process will cancel ASAP.

   119

 *

   120

 * For buffered I/O, the any buffered data is discarded.

   121

 *

   122

 * Note that you do not need to call render_remote_free after this.

   123

 */

   124

void render_remote_cancel (struct render_remote *ctx);

   125

   126

/*

   127

 * Mark a non-buffered custom-I/O request as succesfully completed. This will

   128

 * also free the given ctx.

   129

 */

   130

void render_remote_done (struct render_remote *ctx);

   131

   132

/*

   133

 * Free the render_remote ctx and its assoicated resources. Only valid after a

   134

 * cb_done/cb_fail, otherwise use render_remote_cancel.

   135

 */

   136

void render_remote_free (struct render_remote *ctx);

   137

   138

#endif /* RENDER_REMOTE_H */