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 9
  50 struct foo_state *a = tevent_req_data(req, struct foo_state);
  51
  52 // b->y contains 10
  53 struct testA *b = tevent_req_callback_data(req, struct testA);
  54
  55 // c->y contains 10
  56 struct testA *c = (struct testA *)tevent_req_callback_data_void(req);
  57
  58 printf("a->x: %d\n", a->x);
  59 printf("b->y: %d\n", b->y);
  60 printf("c->y: %d\n", c->y);
  61 }
  62
  63
  64 struct tevent_req * foo_send(TALLOC_CTX *mem_ctx, struct tevent_context *event_ctx) {
  65
  66 printf("_send\n");
  67 struct tevent_req *req;
  68 struct foo_state *state;
  69
  70 req = tevent_req_create(event_ctx, &state, struct foo_state);
  71 state->x = 10;
  72
  73 return req;
  74 }
  75
  76 static void run(struct tevent_context *ev, struct tevent_timer *te,
  77                 struct timeval current_time, void *private_data) {
  78     struct tevent_req *req;
  79     struct testA *tmp = talloc(ev, struct testA);
  80     tmp->y = 9;
  81     req = foo_send(ev, ev);
  82
  83     tevent_req_set_callback(req, foo_done, tmp);
  84     tevent_req_done(req);
  85
  86 }
  87
  88 int main (int argc, char **argv) {
  89
  90     struct tevent_context *event_ctx;
  91     struct testA *data;
  92     TALLOC_CTX *mem_ctx;
  93     struct tevent_timer *time_event;
  94
  95     mem_ctx = talloc_new(NULL); //parent
  96     if (mem_ctx == NULL)
  97         return EXIT_FAILURE;
  98
  99     event_ctx = tevent_context_init(mem_ctx);
 100     if (event_ctx == NULL)
 101         return EXIT_FAILURE;
 102
 103     data = talloc(mem_ctx, struct testA);
 104     data->y = 10;
 105
 106     time_event = tevent_add_timer(event_ctx,
 107                                   mem_ctx,
 108                                   tevent_timeval_current(),
 109                                   run,
 110                                   data);
 111     if (time_event == NULL) {
 112         fprintf(stderr, " FAILED\n");
 113         return EXIT_FAILURE;
 114     }
 115
 116     tevent_loop_once(event_ctx);
 117
 118     talloc_free(mem_ctx);
 119
 120     printf("Quit\n");
 121     return EXIT_SUCCESS;
 122 }
 123 @endcode
 124
 125 Output of this example is:
 126
 127 @code
 128 a->x: 9
 129 b->y: 10
 130 c->y: 10
 131 @endcode
 132
 133 */