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 Note
  68
  69 Refer to http://www.amanda.org/docs/eventapi.html for the current version of
  70 this document.
  71
  72  Introduction
  73
  74 This is a document of the API for the event handler. The purpose of the event
  75 handler is to allow scheduling and serialization of multiple different types of
  76 events.
  77
  78  The API
  79
  80
  81  event_register
  82
  83 event_handle_t *event_register(event_id_t data, event_type_t type, event_fn_t
  84 callback, void *arg);
  85 Sets up an event of the given type to call the given function with the given
  86 argument.
  87 The 'data' argument is type specific.
  88 EV_READFD, EV_WRITEFD - the file descriptor to monitor EV_SIG - the signal
  89 number to monitor EV_TIME - the number of seconds between each pulse EV_WAIT -
  90 the wait identifier used with event_wakeup() EV_DEAD - internal use only
  91
  92  event_release
  93
  94 void event_release(event_handle_t *handle);
  95 Remove an event from the queue. This can happen at any time, even while the
  96 event is firing.
  97
  98  event_loop
  99
 100 void event_loop(int dontblock);
 101 Process all pending events. If the argument is zero, this will keep running
 102 until all events have been released. If the argument is nonzero, this will do
 103 one pass over all pending events, and fire the ones that are immediately ready,
 104 and then return.
 105
 106  event_wait
 107
 108 void event_wait(event_id_t id);
 109 Like event_loop(0), except that it will stop as soon as the event id is
 110 serviced.
 111
 112  event_wakeup
 113
 114 int event_wakeup(event_id_t id);
 115 Fire all EV_WAIT events registered with an argument value of 'id' immediately.
 116 Returns the number of events that were fired.
 117
 118  Data types
 119
 120
 121  event_handle_t
 122
 123 This is an opaque structure that describes a registered event. It is only
 124 useful to keep if you need to unregister the event later.
 125
 126  event_id_t
 127
 128 This is type-specific data. The contents and format depend on on the type of
 129 the event. This is an unsigned integral type.
 130
 131  event_type_t
 132
 133 This is an enumerated type describing the different events we handle.
 134
 135  event_fn_t
 136
 137 typedef void (*event_fn_t)(void *arg);
 138 This is a function signature for the type of function that needs to get passed
 139 to event_register. The argument to the function is a pointer of the caller's
 140 choosing.
 141
 142  Event Types
 143
 144
 145  EV_READFD
 146
 147 This type of event will fire when the file descriptor passed to event_register
 148 has data waiting to be read.
 149
 150  EV_WRITEFD
 151
 152 This type of event will fire when the file descriptor passed to event_register
 153 can have data written to it without blocking.
 154
 155  EV_SIG
 156
 157 This type of event will fire when the signal number passed to event_register
 158 has been caught. Note that if a signal is caught while processing is not in
 159 event_loop(), the event will be delayed until processing returns to event_loop
 160 ().
 161
 162  EV_TIME
 163
 164 This type of event will fire repeatedly with a delay of the number of seconds
 165 passed to event_register between each interval.
 166
 167  EV_WAIT
 168
 169 This type of event will fire when someone calls event_wakeup() with the numeric
 170 argument equal to the argument this event was registered with.
 171 -------------------------------------------------------------------------------
 172
 173 Prev                           Up                              Next
 174 Chapter 24. Amanda Internals  Home  Chapter 26. Amanda Security API
 175