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

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