… | |
… | |
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 | |
|
|
69 | This document documents the libev software package. |
68 | |
70 | |
69 | The newest version of this document is also available as an html-formatted |
71 | The newest version of this document is also available as an html-formatted |
70 | web page you might find easier to navigate when reading it for the first |
72 | web page you might find easier to navigate when reading it for the first |
71 | time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. |
73 | time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. |
|
|
74 | |
|
|
75 | While this document tries to be as complete as possible in documenting |
|
|
76 | libev, its usage and the rationale behind its design, it is not a tutorial |
|
|
77 | on event-based programming, nor will it introduce event-based programming |
|
|
78 | with libev. |
|
|
79 | |
|
|
80 | Familarity with event based programming techniques in general is assumed |
|
|
81 | throughout this document. |
|
|
82 | |
|
|
83 | =head1 ABOUT LIBEV |
72 | |
84 | |
73 | Libev is an event loop: you register interest in certain events (such as a |
85 | Libev is an event loop: you register interest in certain events (such as a |
74 | file descriptor being readable or a timeout occurring), and it will manage |
86 | file descriptor being readable or a timeout occurring), and it will manage |
75 | these event sources and provide your program with events. |
87 | these event sources and provide your program with events. |
76 | |
88 | |
… | |
… | |
110 | name C<loop> (which is always of type C<ev_loop *>) will not have |
122 | name C<loop> (which is always of type C<ev_loop *>) will not have |
111 | this argument. |
123 | this argument. |
112 | |
124 | |
113 | =head2 TIME REPRESENTATION |
125 | =head2 TIME REPRESENTATION |
114 | |
126 | |
115 | Libev represents time as a single floating point number, representing the |
127 | Libev represents time as a single floating point number, representing |
116 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
128 | the (fractional) number of seconds since the (POSIX) epoch (somewhere |
117 | the beginning of 1970, details are complicated, don't ask). This type is |
129 | near the beginning of 1970, details are complicated, don't ask). This |
118 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
130 | type is called C<ev_tstamp>, which is what you should use too. It usually |
119 | to the C<double> type in C, and when you need to do any calculations on |
131 | aliases to the C<double> type in C. When you need to do any calculations |
120 | it, you should treat it as some floating point value. Unlike the name |
132 | on it, you should treat it as some floating point value. Unlike the name |
121 | component C<stamp> might indicate, it is also used for time differences |
133 | component C<stamp> might indicate, it is also used for time differences |
122 | throughout libev. |
134 | throughout libev. |
123 | |
135 | |
124 | =head1 ERROR HANDLING |
136 | =head1 ERROR HANDLING |
125 | |
137 | |
… | |
… | |
1096 | or might not have been clamped to the valid range. |
1108 | or might not have been clamped to the valid range. |
1097 | |
1109 | |
1098 | The default priority used by watchers when no priority has been set is |
1110 | The default priority used by watchers when no priority has been set is |
1099 | always C<0>, which is supposed to not be too high and not be too low :). |
1111 | always C<0>, which is supposed to not be too high and not be too low :). |
1100 | |
1112 | |
1101 | See L<WATCHER PRIORITIES>, below, for a more thorough treatment of |
1113 | See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of |
1102 | priorities. |
1114 | priorities. |
1103 | |
1115 | |
1104 | =item ev_invoke (loop, ev_TYPE *watcher, int revents) |
1116 | =item ev_invoke (loop, ev_TYPE *watcher, int revents) |
1105 | |
1117 | |
1106 | Invoke the C<watcher> with the given C<loop> and C<revents>. Neither |
1118 | Invoke the C<watcher> with the given C<loop> and C<revents>. Neither |
… | |
… | |
4094 | involves iterating over all running async watchers or all signal numbers. |
4106 | involves 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 | |
|
|
4117 | A watcher is active as long as it has been started (has been attached to |
|
|
4118 | an event loop) but not yet stopped (disassociated from the event loop). |
|
|
4119 | |
|
|
4120 | =item application |
|
|
4121 | |
|
|
4122 | In this document, an application is whatever is using libev. |
|
|
4123 | |
|
|
4124 | =item callback |
|
|
4125 | |
|
|
4126 | The address of a function that is called when some event has been |
|
|
4127 | detected. Callbacks are being passed the event loop, the watcher that |
|
|
4128 | received the event, and the actual event bitset. |
|
|
4129 | |
|
|
4130 | =item callback invocation |
|
|
4131 | |
|
|
4132 | The act of calling the callback associated with a watcher. |
|
|
4133 | |
|
|
4134 | =item event |
|
|
4135 | |
|
|
4136 | A change of state of some external event, such as data now being available |
|
|
4137 | for reading on a file descriptor, time having passed or simply not having |
|
|
4138 | any other events happening anymore. |
|
|
4139 | |
|
|
4140 | In libev, events are represented as single bits (such as C<EV_READ> or |
|
|
4141 | C<EV_TIMEOUT>). |
|
|
4142 | |
|
|
4143 | =item event library |
|
|
4144 | |
|
|
4145 | A software package implementing an event model and loop. |
|
|
4146 | |
|
|
4147 | =item event loop |
|
|
4148 | |
|
|
4149 | An entity that handles and processes external events and converts them |
|
|
4150 | into callback invocations. |
|
|
4151 | |
|
|
4152 | =item event model |
|
|
4153 | |
|
|
4154 | The model used to describe how an event loop handles and processes |
|
|
4155 | watchers and events. |
|
|
4156 | |
|
|
4157 | =item pending |
|
|
4158 | |
|
|
4159 | A watcher is pending as soon as the corresponding event has been detected, |
|
|
4160 | and stops being pending as soon as the watcher will be invoked or its |
|
|
4161 | pending status is explicitly cleared by the application. |
|
|
4162 | |
|
|
4163 | A watcher can be pending, but not active. Stopping a watcher also clears |
|
|
4164 | its pending status. |
|
|
4165 | |
|
|
4166 | =item real time |
|
|
4167 | |
|
|
4168 | The physical time that is observed. It is apparently strictly monotonic :) |
|
|
4169 | |
|
|
4170 | =item wall-clock time |
|
|
4171 | |
|
|
4172 | The time and date as shown on clocks. Unlike real time, it can actually |
|
|
4173 | be wrong and jump forwards and backwards, e.g. when the you adjust your |
|
|
4174 | clock. |
|
|
4175 | |
|
|
4176 | =item watcher |
|
|
4177 | |
|
|
4178 | A data structure that describes interest in certain events. Watchers need |
|
|
4179 | to be started (attached to an event loop) before they can receive events. |
|
|
4180 | |
|
|
4181 | =item watcher invocation |
|
|
4182 | |
|
|
4183 | The act of calling the callback associated with a watcher. |
|
|
4184 | |
|
|
4185 | =back |
|
|
4186 | |
4099 | =head1 AUTHOR |
4187 | =head1 AUTHOR |
4100 | |
4188 | |
4101 | Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. |
4189 | Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. |
4102 | |
4190 | |