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"

     9

    10

/*

    11

 * Execute a render operation on a remote render_node

    12

 */

    13

    14

    15

#define RENDER_PORT_NAME "6159"

    16

    17

struct render_remote;

    18

    19

/*

    20

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

    21

 * address, and buffer the data stream.

    22

 *

    23

 * The various callback functions must all be provided!

    24

 *

    25

 * cb_sent

    26

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

    27

 *  complete succesfully.

    28

 *

    29

 * cb_data

    30

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

    31

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

    32

 *  render_remote_flush.

    33

 *

    34

 * cb_done

    35

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

    36

 *  our buffer by cb_data

    37

 *

    38

 * cb_fail 

    39

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

    40

 *  after cb_done has been called.

    41

 *

    42

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

    43

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

    44

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

    45

 * cancel it using render_remote_cancel.

    46

 *

    47

 * Returns NULL on error, or a handle on success

    48

 */

    49

struct render_remote *render_remote (

    50

        struct render *render,              // what to render

    52

        void (*cb_sent)(void *arg),

    53

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

    54

        void (*cb_done)(void *arg),

    55

        void (*cb_fail)(void *arg),

    56

        void *cb_arg

    57

);

    58

    59

/*

    60

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

    61

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

    62

 *

    63

 * The various callback functions must all be provided!

    64

 *

    65

 * cb_sent

    66

 *  Will be called once the request has been sent.

    67

 *

    68

 * cb_fail

    69

 *  Will be called if sending the request fails.

    70

 *

    71

 * cb_io_data

    72

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

    73

 *  re-enabled using render_remote_again each time.

    74

 */

    75

struct render_remote *render_remote_rawio (

    76

        struct render *render,

    78

        void (*cb_sent)(void *arg),

    79

        void (*cb_fail)(void *arg),

    80

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

    81

        void *cb_arg

    82

);

    83

    84

/*

    85

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

    86

 *

    87

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

    88

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

    89

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

    90

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

    91

 * data has been received from the remote end.

    92

 *

    93

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

    94

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

    95

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

    96

 * called any more.

    97

 *

    98

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

    99

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

   100

 * buffer again.

   101

 *

   102

 * Only valid for normal buffered renders.

   103

 */

   104

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

   105

   106

/*

   107

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

   108

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

   109

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

   110

 */

   111

void render_remote_flush (struct render_remote *ctx);

   112

   113

/*

   114

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

   115

 * data is received.

   116

 */

   117

int render_remote_reschedule (struct render_remote *ctx);

   118

   119

/*

   120

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

   121

 * and the remote render process will cancel ASAP.

   122

 *

   123

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

   124

 *

   125

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

   126

 */

   127

void render_remote_cancel (struct render_remote *ctx);

   128

   129

/*

   130

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

   131

 * also free the given ctx.

   132

 */

   133

void render_remote_done (struct render_remote *ctx);

   134

   135

/*

   136

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

   137

 * cb_done/cb_fail, otherwise use render_remote_cancel.

   138

 */

   139

void render_remote_free (struct render_remote *ctx);

   140

   141

#endif /* RENDER_REMOTE_H */