lib/tevent/doc/tevent_context.dox

   1 /**
   2 @page tevent_context Chapter 1: Tevent context
   3
   4 @section context Tevent context
   5
   6 Tevent context is an essential logical unit of tevent library. For working with
   7 events at least one such context has to be created - allocated, initialized.
   8 Then, events which are meant to be caught and handled have to be registered
   9 within this specific context. Reason for subordinating events to a tevent
  10 context structure rises from the fact that several context can be created and
  11 each of them is processed at different time. So, there can be 1 context
  12 containing just file descriptor events, another one taking care of signal and
  13 time events and the third one which keeps information about the rest.
  14
  15 Tevent loops are the part of the library which represents the mechanism where
  16 noticing events and triggering handlers actually happens. They accept just one
  17 argument - tevent context structure. Therefore if theoretically an infinity
  18 loop (tevent_loop_wait) was called, only those arguments which belong to the
  19 passed tevent context structure can be caught and invoked within this call.
  20 Although some more signal events were registered (but within some other
  21 context) they will not be noticed.
  22
  23 @subsection Example
  24
  25 First lines which handle <code>mem_ctx</code> belong to talloc library
  26 knowledge but because of the fact that tevent uses the talloc library for its
  27 mechanisms it is necessary to understand a bit talloc as well. For more
  28 information about working with talloc, please visit <a
  29 href="http://talloc.samba.org/">talloc website</a> where tutorial and
  30 documentation are located.
  31
  32 Tevent context structure <code>*event_ctx</code> represents the unit which will
  33 further contain information about registered events. It is created via calling
  34 tevent_context_init().
  35
  36 @code
  37 TALLOC_CTX *mem_ctx = talloc_new(NULL);
  38 if (mem_ctx == NULL) {
  39     // error handling
  40 }
  41
  42 struct tevent_context *ev_ctx = tevent_context_init(mem_ctx);
  43 if(ev_ctx == NULL) {
  44     // error handling
  45 }
  46 @endcode
  47
  48 Tevent context has a structure containing lots of information. It include lists
  49 of all events which are divided according their type and are in order showing
  50 the sequence as they came.
  51
  52 @image html tevent_context_stucture.png
  53
  54 In addition to the lists shown in the diagram, the tevent context also contains
  55 many other data (e.g. information about the available system mechanism for
  56 triggering callbacks).
  57
  58 @section tevent_loops Tevent loops
  59
  60 Tevent loops are the dispatcher for events. They catch them and trigger the
  61 handlers. In the case of longer processes, the program spends most of its time
  62 at this point waiting for events, invoking handlers and waiting for another
  63 event again. There are 2 types of loop available for use in tevent library:
  64
  65 <ul>
  66 <li>int tevent_loop_wait()</li>
  67 <li>int tevent_loop_once()</li>
  68 </ul>
  69
  70 Both of functions accept just one parametr (tevent context) and the only
  71 difference lies in the fact that the first loop can theoretically last for ever
  72 but the second one will wait just for a single one event to catch and then the
  73 loop breaks and the program continue.
  74
  75 */