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

Comparing libev/ev.pod (file contents):
Revision 1.8 by root, Mon Nov 12 08:20:02 2007 UTC vs.
Revision 1.9 by root, Mon Nov 12 08:29:11 2007 UTC

… …
63you linked against by calling the functions C<ev_version_major> and 63you linked against by calling the functions C<ev_version_major> and
64C<ev_version_minor>. If you want, you can compare against the global 64C<ev_version_minor>. If you want, you can compare against the global
65symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the 65symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
66version of the library your program was compiled against. 66version of the library your program was compiled against.
67 67
68Usually, its a good idea to terminate if the major versions mismatch, 68Usually, it's a good idea to terminate if the major versions mismatch,
69as this indicates an incompatible change. Minor versions are usually 69as this indicates an incompatible change. Minor versions are usually
70compatible to older versions, so a larger minor version alone is usually 70compatible to older versions, so a larger minor version alone is usually
71not a problem. 71not a problem.
72 72
73=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 73=item ev_set_allocator (void *(*cb)(void *ptr, long size))
… …
103If you use threads, a common model is to run the default event loop 103If you use threads, a common model is to run the default event loop
104in your main thread (or in a separate thrad) and for each thread you 104in your main thread (or in a separate thrad) and for each thread you
105create, you also create another event loop. Libev itself does no locking 105create, you also create another event loop. Libev itself does no locking
106whatsoever, so if you mix calls to the same event loop in different 106whatsoever, so if you mix calls to the same event loop in different
107threads, make sure you lock (this is usually a bad idea, though, even if 107threads, make sure you lock (this is usually a bad idea, though, even if
108done correctly, because its hideous and inefficient). 108done correctly, because it's hideous and inefficient).
109 109
110=over 4 110=over 4
111 111
112=item struct ev_loop *ev_default_loop (unsigned int flags) 112=item struct ev_loop *ev_default_loop (unsigned int flags)
113 113
… …
126 126
127=over 4 127=over 4
128 128
129=item EVFLAG_AUTO 129=item EVFLAG_AUTO
130 130
131The default flags value. Use this if you have no clue (its the right 131The default flags value. Use this if you have no clue (it's the right
132thing, believe me). 132thing, believe me).
133 133
134=item EVFLAG_NOENV 134=item EVFLAG_NOENV
135 135
136If this flag bit is ored into the flag value (or the program runs setuid 136If this flag bit is ored into the flag value (or the program runs setuid
… …
138C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 138C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
139override the flags completely if it is found in the environment. This is 139override the flags completely if it is found in the environment. This is
140useful to try out specific backends to test their performance, or to work 140useful to try out specific backends to test their performance, or to work
141around bugs. 141around bugs.
142 142
143=item EVMETHOD_SELECT portable select backend 143=item EVMETHOD_SELECT (portable select backend)
144 144
145=item EVMETHOD_POLL poll backend (everywhere except windows) 145=item EVMETHOD_POLL (poll backend, available everywhere except on windows)
146 146
147=item EVMETHOD_EPOLL linux only 147=item EVMETHOD_EPOLL (linux only)
148 148
149=item EVMETHOD_KQUEUE some bsds only 149=item EVMETHOD_KQUEUE (some bsds only)
150 150
151=item EVMETHOD_DEVPOLL solaris 8 only 151=item EVMETHOD_DEVPOLL (solaris 8 only)
152 152
153=item EVMETHOD_PORT solaris 10 only 153=item EVMETHOD_PORT (solaris 10 only)
154 154
155If one or more of these are ored into the flags value, then only these 155If one or more of these are ored into the flags value, then only these
156backends will be tried (in the reverse order as given here). If one are 156backends will be tried (in the reverse order as given here). If one are
157specified, any backend will do. 157specified, any backend will do.
158 158
… …
167 167
168=item ev_default_destroy () 168=item ev_default_destroy ()
169 169
170Destroys the default loop again (frees all memory and kernel state 170Destroys the default loop again (frees all memory and kernel state
171etc.). This stops all registered event watchers (by not touching them in 171etc.). This stops all registered event watchers (by not touching them in
172any way whatsoever, although you cnanot rely on this :). 172any way whatsoever, although you cannot rely on this :).
173 173
174=item ev_loop_destroy (loop) 174=item ev_loop_destroy (loop)
175 175
176Like C<ev_default_destroy>, but destroys an event loop created by an 176Like C<ev_default_destroy>, but destroys an event loop created by an
177earlier call to C<ev_loop_new>. 177earlier call to C<ev_loop_new>.
… …
185 185
186You I<must> call this function after forking if and only if you want to 186You I<must> call this function after forking if and only if you want to
187use the event library in both processes. If you just fork+exec, you don't 187use the event library in both processes. If you just fork+exec, you don't
188have to call it. 188have to call it.
189 189
190The function itself is quite fast and its usually not a problem to call 190The function itself is quite fast and it's usually not a problem to call
191it just in case after a fork. To make this easy, the function will fit in 191it just in case after a fork. To make this easy, the function will fit in
192quite nicely into a call to C<pthread_atfork>: 192quite nicely into a call to C<pthread_atfork>:
193 193
194 pthread_atfork (0, 0, ev_default_fork); 194 pthread_atfork (0, 0, ev_default_fork);
195 195
… …
202=item unsigned int ev_method (loop) 202=item unsigned int ev_method (loop)
203 203
204Returns one of the C<EVMETHOD_*> flags indicating the event backend in 204Returns one of the C<EVMETHOD_*> flags indicating the event backend in
205use. 205use.
206 206
207=item ev_tstamp = ev_now (loop) 207=item ev_tstamp ev_now (loop)
208 208
209Returns the current "event loop time", which is the time the event loop 209Returns the current "event loop time", which is the time the event loop
210got events and started processing them. This timestamp does not change 210got events and started processing them. This timestamp does not change
211as long as callbacks are being processed, and this is also the base time 211as long as callbacks are being processed, and this is also the base time
212used for relative timers. You can treat it as the timestamp of the event 212used for relative timers. You can treat it as the timestamp of the event
… …
221If the flags argument is specified as 0, it will not return until either 221If the flags argument is specified as 0, it will not return until either
222no event watchers are active anymore or C<ev_unloop> was called. 222no event watchers are active anymore or C<ev_unloop> was called.
223 223
224A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 224A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
225those events and any outstanding ones, but will not block your process in 225those events and any outstanding ones, but will not block your process in
226case there are no events. 226case there are no events and will return after one iteration of the loop.
227 227
228A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 228A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
229neccessary) and will handle those and any outstanding ones. It will block 229neccessary) and will handle those and any outstanding ones. It will block
230your process until at least one new event arrives. 230your process until at least one new event arrives, and will return after
231one iteration of the loop.
231 232
232This flags value could be used to implement alternative looping 233This flags value could be used to implement alternative looping
233constructs, but the C<prepare> and C<check> watchers provide a better and 234constructs, but the C<prepare> and C<check> watchers provide a better and
234more generic mechanism. 235more generic mechanism.
235 236
236=item ev_unloop (loop, how) 237=item ev_unloop (loop, how)
237 238
238Can be used to make a call to C<ev_loop> return early. The C<how> argument 239Can be used to make a call to C<ev_loop> return early (but only after it
240has processed all outstanding events). The C<how> argument must be either
239must be either C<EVUNLOOP_ONCE>, which will make the innermost C<ev_loop> 241C<EVUNLOOP_ONCE>, which will make the innermost C<ev_loop> call return, or
240call return, or C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> 242C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
241calls return.
242 243
243=item ev_ref (loop) 244=item ev_ref (loop)
244 245
245=item ev_unref (loop) 246=item ev_unref (loop)
246 247
247Ref/unref can be used to add or remove a refcount on the event loop: Every 248Ref/unref can be used to add or remove a reference count on the event
248watcher keeps one reference. If you have a long-runing watcher you never 249loop: Every watcher keeps one reference, and as long as the reference
249unregister that should not keep ev_loop from running, ev_unref() after 250count is nonzero, C<ev_loop> will not return on its own. If you have
250starting, and ev_ref() before stopping it. Libev itself uses this for 251a watcher you never unregister that should not keep C<ev_loop> from
251example for its internal signal pipe: It is not visible to you as a user 252returning, ev_unref() after starting, and ev_ref() before stopping it. For
252and should not keep C<ev_loop> from exiting if the work is done. It is 253example, libev itself uses this for its internal signal pipe: It is not
253also an excellent way to do this for generic recurring timers or from 254visible to the libev user and should not keep C<ev_loop> from exiting if
254within third-party libraries. Just remember to unref after start and ref 255no event watchers registered by it are active. It is also an excellent
255before stop. 256way to do this for generic recurring timers or from within third-party
257libraries. Just remember to I<unref after start> and I<ref before stop>.
256 258
257=back 259=back
258 260
259=head1 ANATOMY OF A WATCHER 261=head1 ANATOMY OF A WATCHER
260 262
… …
446The timers are based on real time, that is, if you register an event that 448The timers are based on real time, that is, if you register an event that
447times out after an hour and youreset your system clock to last years 449times out after an hour and youreset your system clock to last years
448time, it will still time out after (roughly) and hour. "Roughly" because 450time, it will still time out after (roughly) and hour. "Roughly" because
449detecting time jumps is hard, and soem inaccuracies are unavoidable (the 451detecting time jumps is hard, and soem inaccuracies are unavoidable (the
450monotonic clock option helps a lot here). 452monotonic clock option helps a lot here).
453
454The relative timeouts are calculated relative to the C<ev_now ()>
455time. This is usually the right thing as this timestamp refers to the time
456of the event triggering whatever timeout you are modifying/starting. If
457you suspect event processing to be delayed and you *need* to base the timeout
458ion the current time, use something like this to adjust for this:
459
460 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
451 461
452=over 4 462=over 4
453 463
454=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 464=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
455 465
… …
585 595
586=head2 ev_signal - signal me when a signal gets signalled 596=head2 ev_signal - signal me when a signal gets signalled
587 597
588Signal watchers will trigger an event when the process receives a specific 598Signal watchers will trigger an event when the process receives a specific
589signal one or more times. Even though signals are very asynchronous, libev 599signal one or more times. Even though signals are very asynchronous, libev
590will try its best to deliver signals synchronously, i.e. as part of the 600will try it's best to deliver signals synchronously, i.e. as part of the
591normal event processing, like any other event. 601normal event processing, like any other event.
592 602
593You cna configure as many watchers as you like per signal. Only when the 603You cna configure as many watchers as you like per signal. Only when the
594first watcher gets started will libev actually register a signal watcher 604first watcher gets started will libev actually register a signal watcher
595with the kernel (thus it coexists with your own signal handlers as long 605with the kernel (thus it coexists with your own signal handlers as long

Diff Legend

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