git.gag.com Git - debian/amanda/blob - docs/eventapi.txt

   1
   2          Chapter 25. Amanda Event API
   3 Prev  Part V. Technical Background  Next
   4
   5 -------------------------------------------------------------------------------
   6
   7 Chapter 25. Amanda Event API
   8
   9
  10 Mike Grupenhoff
  11
  12 Original text
  13 AMANDA Core Team
  14 <kashmir@munge.com>
  15
  16 Stefan G. Weichinger
  17
  18 XML-conversion;Updates
  19 AMANDA Core Team
  20 <sgw@amanda.org>
  21 Table of Contents
  22
  23
  24   Introduction
  25
  26   The_API
  27
  28
  29         event_register
  30
  31         event_release
  32
  33         event_loop
  34
  35         event_wait
  36
  37         event_wakeup
  38
  39
  40   Data_types
  41
  42
  43         event_handle_t
  44
  45         event_id_t
  46
  47         event_type_t
  48
  49         event_fn_t
  50
  51
  52   Event_Types
  53
  54
  55         EV_READFD
  56
  57         EV_WRITEFD
  58
  59         EV_SIG
  60
  61         EV_TIME
  62
  63         EV_WAIT
  64
  65
  66
  67  Introduction
  68
  69 This is a document of the API for the event handler. The purpose of the event
  70 handler is to allow scheduling and serialization of multiple different types of
  71 events.
  72
  73  The API
  74
  75
  76  event_register
  77
  78 event_handle_t *event_register(event_id_t data, event_type_t type, event_fn_t
  79 callback, void *arg);
  80 Sets up an event of the given type to call the given function with the given
  81 argument.
  82 The 'data' argument is type specific.
  83 EV_READFD, EV_WRITEFD - the file descriptor to monitor EV_SIG - the signal
  84 number to monitor EV_TIME - the number of seconds between each pulse EV_WAIT -
  85 the wait identifier used with event_wakeup() EV_DEAD - internal use only
  86
  87  event_release
  88
  89 void event_release(event_handle_t *handle);
  90 Remove an event from the queue. This can happen at any time, even while the
  91 event is firing.
  92
  93  event_loop
  94
  95 void event_loop(int dontblock);
  96 Process all pending events. If the argument is zero, this will keep running
  97 until all events have been released. If the argument is nonzero, this will do
  98 one pass over all pending events, and fire the ones that are immediately ready,
  99 and then return.
 100
 101  event_wait
 102
 103 void event_wait(event_id_t id);
 104 Like event_loop(0), except that it will stop as soon as the event id is
 105 serviced.
 106
 107  event_wakeup
 108
 109 int event_wakeup(event_id_t id);
 110 Fire all EV_WAIT events registered with an argument value of 'id' immediately.
 111 Returns the number of events that were fired.
 112
 113  Data types
 114
 115
 116  event_handle_t
 117
 118 This is an opaque structure that describes a registered event. It is only
 119 useful to keep if you need to unregister the event later.
 120
 121  event_id_t
 122
 123 This is type-specific data. The contents and format depend on on the type of
 124 the event. This is an unsigned integral type.
 125
 126  event_type_t
 127
 128 This is an enumerated type describing the different events we handle.
 129
 130  event_fn_t
 131
 132 typedef void (*event_fn_t)(void *arg);
 133 This is a function signature for the type of function that needs to get passed
 134 to event_register. The argument to the function is a pointer of the caller's
 135 choosing.
 136
 137  Event Types
 138
 139
 140  EV_READFD
 141
 142 This type of event will fire when the file descriptor passed to event_register
 143 has data waiting to be read.
 144
 145  EV_WRITEFD
 146
 147 This type of event will fire when the file descriptor passed to event_register
 148 can have data written to it without blocking.
 149
 150  EV_SIG
 151
 152 This type of event will fire when the signal number passed to event_register
 153 has been caught. Note that if a signal is caught while processing is not in
 154 event_loop(), the event will be delayed until processing returns to event_loop
 155 ().
 156
 157  EV_TIME
 158
 159 This type of event will fire repeatedly with a delay of the number of seconds
 160 passed to event_register between each interval.
 161
 162  EV_WAIT
 163
 164 This type of event will fire when someone calls event_wakeup() with the numeric
 165 argument equal to the argument this event was registered with.
 166
 167 Note
 168
 169 Refer to http://www.amanda.org/docs/eventapi.html for the current version of
 170 this document.
 171 -------------------------------------------------------------------------------
 172
 173 Prev                           Up                              Next
 174 Chapter 24. Amanda Internals  Home  Chapter 26. Amanda Security API
 175