lib/tevent/doc/tevent_data.dox

   1 /**
   2 @page tevent_data Chapter 3: Accessing data
   3 @section data Accessing data with tevent
   4
   5 A tevent request is (usually) created together with a structure for storing the
   6 data necessary for an asynchronous computation. For these private data, tevent
   7 library uses void (generic) pointers, therefore any data type can be very
   8 simply pointed at. However, this attitude requires clear and guaranteed
   9 knowledge of the data type that will be handled, in advance. Private data can
  10 be of 2 types: connected with a request itself or given as an individual
  11 argument to a callback. It is necessary to differentiate these types, because
  12 there is a slightly different method of data access for each. There are two
  13 possibilities how to access data that is given as an argument directly to a
  14 callback. The difference lies in the pointer that is returned. In one case it
  15 is the data type specified in the function’s argument, in another void* is
  16 returned.
  17
  18 @code
  19 void tevent_req_callback_data (struct tevent_req *req, #type)
  20 void tevent_req_callback_data_void (struct tevent_req *req)
  21 @endcode
  22
  23
  24 To obtain data that are strictly bound to a request, this function is the only
  25 direct procedure.
  26
  27 @code
  28 void *tevent_req_data (struct tevent_req *req, #type)
  29 @endcode
  30
  31 Example with both calls which differs between private data within tevent
  32 request and data handed over as an argument.
  33
  34 @code
  35 #include <stdio.h>
  36 #include <unistd.h>
  37 #include <tevent.h>
  38
  39 struct foo_state {
  40     int x;
  41 };
  42
  43 struct testA {
  44     int y;
  45 };
  46
  47
  48 static void foo_done(struct tevent_req *req) {
  49     // a->x contains 10 since it came from foo_send
  50     struct foo_state *a = tevent_req_data(req, struct foo_state);
  51
  52     // b->y contains 9 since it came from run
  53     struct testA *b = tevent_req_callback_data(req, struct testA);
  54
  55     // c->y contains 9 since it came from run we just used a different way
  56     // of getting it.
  57     struct testA *c = (struct testA *)tevent_req_callback_data_void(req);
  58
  59     printf("a->x: %d\n", a->x);
  60     printf("b->y: %d\n", b->y);
  61     printf("c->y: %d\n", c->y);
  62 }
  63
  64
  65 struct tevent_req * foo_send(TALLOC_CTX *mem_ctx, struct tevent_context *event_ctx) {
  66
  67 printf("_send\n");
  68 struct tevent_req *req;
  69 struct foo_state *state;
  70
  71 req = tevent_req_create(event_ctx, &state, struct foo_state);
  72 state->x = 10;
  73
  74 return req;
  75 }
  76
  77 static void run(struct tevent_context *ev, struct tevent_timer *te,
  78                 struct timeval current_time, void *private_data) {
  79     struct tevent_req *req;
  80     struct testA *tmp = talloc(ev, struct testA);
  81
  82     // Note that we did not use the private data passed in
  83
  84     tmp->y = 9;
  85     req = foo_send(ev, ev);
  86
  87     tevent_req_set_callback(req, foo_done, tmp);
  88     tevent_req_done(req);
  89
  90 }
  91
  92 int main (int argc, char **argv) {
  93
  94     struct tevent_context *event_ctx;
  95     struct testA *data;
  96     TALLOC_CTX *mem_ctx;
  97     struct tevent_timer *time_event;
  98
  99     mem_ctx = talloc_new(NULL); //parent
 100     if (mem_ctx == NULL)
 101         return EXIT_FAILURE;
 102
 103     event_ctx = tevent_context_init(mem_ctx);
 104     if (event_ctx == NULL)
 105         return EXIT_FAILURE;
 106
 107     data = talloc(mem_ctx, struct testA);
 108     data->y = 11;
 109
 110     time_event = tevent_add_timer(event_ctx,
 111                                   mem_ctx,
 112                                   tevent_timeval_current(),
 113                                   run,
 114                                   data);
 115     if (time_event == NULL) {
 116         fprintf(stderr, " FAILED\n");
 117         return EXIT_FAILURE;
 118     }
 119
 120     tevent_loop_once(event_ctx);
 121
 122     talloc_free(mem_ctx);
 123
 124     printf("Quit\n");
 125     return EXIT_SUCCESS;
 126 }
 127 @endcode
 128
 129 Output of this example is:
 130
 131 @code
 132 a->x: 10
 133 b->y: 9
 134 c->y: 9
 135 @endcode
 136
 137 */