ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.233 by root, Thu Apr 16 07:32:51 2009 UTC vs.
Revision 1.236 by root, Thu Apr 16 07:56:05 2009 UTC

… …
62 62
63 // unloop was called, so exit 63 // unloop was called, so exit
64 return 0; 64 return 0;
65 } 65 }
66 66
67=head1 DESCRIPTION 67=head1 ABOUT THIS DOCUMENT
68
69This document documents the libev software package.
68 70
69The newest version of this document is also available as an html-formatted 71The newest version of this document is also available as an html-formatted
70web page you might find easier to navigate when reading it for the first 72web page you might find easier to navigate when reading it for the first
71time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. 73time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
74
75While this document tries to be as complete as possible in documenting
76libev, its usage and the rationale behind its design, it is not a tutorial
77on event-based programming, nor will it introduce event-based programming
78with libev.
79
80Familarity with event based programming techniques in general is assumed
81throughout this document.
82
83=head1 ABOUT LIBEV
72 84
73Libev is an event loop: you register interest in certain events (such as a 85Libev is an event loop: you register interest in certain events (such as a
74file descriptor being readable or a timeout occurring), and it will manage 86file descriptor being readable or a timeout occurring), and it will manage
75these event sources and provide your program with events. 87these event sources and provide your program with events.
76 88
… …
1096or might not have been clamped to the valid range. 1108or might not have been clamped to the valid range.
1097 1109
1098The default priority used by watchers when no priority has been set is 1110The default priority used by watchers when no priority has been set is
1099always C<0>, which is supposed to not be too high and not be too low :). 1111always C<0>, which is supposed to not be too high and not be too low :).
1100 1112
1101See L<WATCHER PRIORITIES>, below, for a more thorough treatment of 1113See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1102priorities. 1114priorities.
1103 1115
1104=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1116=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1105 1117
1106Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1118Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
… …
4094involves iterating over all running async watchers or all signal numbers. 4106involves iterating over all running async watchers or all signal numbers.
4095 4107
4096=back 4108=back
4097 4109
4098 4110
4111=head1 GLOSSARY
4112
4113=over 4
4114
4115=item active
4116
4117A watcher is active as long as it has been started (has been attached to
4118an event loop) but not yet stopped (disassociated from the event loop).
4119
4120=item application
4121
4122In this document, an application is whatever is using libev.
4123
4124=item callback
4125
4126The address of a function that is called when some event has been
4127detected. Callbacks are being passed the event loop, the watcher that
4128received the event, and the actual event bitset.
4129
4130=item callback invocation
4131
4132The act of calling the callback associated with a watcher.
4133
4134=item event
4135
4136A change of state of some external event, such as data now being available
4137for reading on a file descriptor, time having passed or simply not having
4138any other events happening anymore.
4139
4140In libev, events are represented as single bits (such as C<EV_READ> or
4141C<EV_TIMEOUT>).
4142
4143=item event library
4144
4145A software package implementing an event model and loop.
4146
4147=item event loop
4148
4149An entity that handles and processes external events and converts them
4150into callback invocations.
4151
4152=item event model
4153
4154The model used to describe how an event loop handles and processes
4155watchers and events.
4156
4157=item pending
4158
4159A watcher is pending as soon as the corresponding event has been detected,
4160and stops being pending as soon as the watcher will be invoked or its
4161pending status is explicitly cleared by the application.
4162
4163A watcher can be pending, but not active. Stopping a watcher also clears
4164its pending status.
4165
4166=item real time
4167
4168The physical time that is observed. It is apparently strictly monotonic :)
4169
4170=item wall-clock time
4171
4172The time and date as shown on clocks. Unlike real time, it can actually
4173be wrong and jump forwards and backwards, e.g. when the you adjust your
4174clock.
4175
4176=item watcher
4177
4178A data structure that describes interest in certain events. Watchers need
4179to be started (attached to an event loop) before they can receive events.
4180
4181=item watcher invocation
4182
4183The act of calling the callback associated with a watcher.
4184
4185=back
4186
4099=head1 AUTHOR 4187=head1 AUTHOR
4100 4188
4101Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 4189Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
4102 4190

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines