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

Comparing libev/ev.pod (file contents):
Revision 1.114 by root, Mon Dec 31 01:31:30 2007 UTC vs.
Revision 1.118 by root, Thu Jan 10 06:00:55 2008 UTC

… …
260flags. If that is troubling you, check C<ev_backend ()> afterwards). 260flags. If that is troubling you, check C<ev_backend ()> afterwards).
261 261
262If you don't know what event loop to use, use the one returned from this 262If you don't know what event loop to use, use the one returned from this
263function. 263function.
264 264
265The default loop is the only loop that can handle C<ev_signal> and
266C<ev_child> watchers, and to do this, it always registers a handler
267for C<SIGCHLD>. If this is a problem for your app you can either
268create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
269can simply overwrite the C<SIGCHLD> signal handler I<after> calling
270C<ev_default_init>.
271
265The flags argument can be used to specify special behaviour or specific 272The flags argument can be used to specify special behaviour or specific
266backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>). 273backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
267 274
268The following flags are supported: 275The following flags are supported:
269 276
… …
403While this backend scales well, it requires one system call per active 410While this backend scales well, it requires one system call per active
404file descriptor per loop iteration. For small and medium numbers of file 411file descriptor per loop iteration. For small and medium numbers of file
405descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 412descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
406might perform better. 413might perform better.
407 414
415On the positive side, ignoring the spurious readyness notifications, this
416backend actually performed to specification in all tests and is fully
417embeddable, which is a rare feat among the OS-specific backends.
418
408=item C<EVBACKEND_ALL> 419=item C<EVBACKEND_ALL>
409 420
410Try all backends (even potentially broken ones that wouldn't be tried 421Try all backends (even potentially broken ones that wouldn't be tried
411with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 422with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
412C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 423C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
… …
414It is definitely not recommended to use this flag. 425It is definitely not recommended to use this flag.
415 426
416=back 427=back
417 428
418If one or more of these are ored into the flags value, then only these 429If one or more of these are ored into the flags value, then only these
419backends will be tried (in the reverse order as given here). If none are 430backends will be tried (in the reverse order as listed here). If none are
420specified, most compiled-in backend will be tried, usually in reverse 431specified, all backends in C<ev_recommended_backends ()> will be tried.
421order of their flag values :)
422 432
423The most typical usage is like this: 433The most typical usage is like this:
424 434
425 if (!ev_default_loop (0)) 435 if (!ev_default_loop (0))
426 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 436 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
… …
590Can be used to make a call to C<ev_loop> return early (but only after it 600Can be used to make a call to C<ev_loop> return early (but only after it
591has processed all outstanding events). The C<how> argument must be either 601has processed all outstanding events). The C<how> argument must be either
592C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 602C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
593C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 603C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
594 604
605This "unloop state" will be cleared when entering C<ev_loop> again.
606
595=item ev_ref (loop) 607=item ev_ref (loop)
596 608
597=item ev_unref (loop) 609=item ev_unref (loop)
598 610
599Ref/unref can be used to add or remove a reference count on the event 611Ref/unref can be used to add or remove a reference count on the event
… …
603returning, ev_unref() after starting, and ev_ref() before stopping it. For 615returning, ev_unref() after starting, and ev_ref() before stopping it. For
604example, libev itself uses this for its internal signal pipe: It is not 616example, libev itself uses this for its internal signal pipe: It is not
605visible to the libev user and should not keep C<ev_loop> from exiting if 617visible to the libev user and should not keep C<ev_loop> from exiting if
606no event watchers registered by it are active. It is also an excellent 618no event watchers registered by it are active. It is also an excellent
607way to do this for generic recurring timers or from within third-party 619way to do this for generic recurring timers or from within third-party
608libraries. Just remember to I<unref after start> and I<ref before stop>. 620libraries. Just remember to I<unref after start> and I<ref before stop>
621(but only if the watcher wasn't active before, or was active before,
622respectively).
609 623
610Example: Create a signal watcher, but keep it from keeping C<ev_loop> 624Example: Create a signal watcher, but keep it from keeping C<ev_loop>
611running when nothing else is active. 625running when nothing else is active.
612 626
613 struct ev_signal exitsig; 627 struct ev_signal exitsig;
… …
2549be detected at runtime. 2563be detected at runtime.
2550 2564
2551=item EV_H 2565=item EV_H
2552 2566
2553The name of the F<ev.h> header file used to include it. The default if 2567The name of the F<ev.h> header file used to include it. The default if
2554undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to 2568undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2555virtually rename the F<ev.h> header file in case of conflicts. 2569used to virtually rename the F<ev.h> header file in case of conflicts.
2556 2570
2557=item EV_CONFIG_H 2571=item EV_CONFIG_H
2558 2572
2559If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 2573If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2560F<ev.c>'s idea of where to find the F<config.h> file, similarly to 2574F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2561C<EV_H>, above. 2575C<EV_H>, above.
2562 2576
2563=item EV_EVENT_H 2577=item EV_EVENT_H
2564 2578
2565Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 2579Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2566of how the F<event.h> header can be found, the dfeault is C<"event.h">. 2580of how the F<event.h> header can be found, the default is C<"event.h">.
2567 2581
2568=item EV_PROTOTYPES 2582=item EV_PROTOTYPES
2569 2583
2570If defined to be C<0>, then F<ev.h> will not define any function 2584If defined to be C<0>, then F<ev.h> will not define any function
2571prototypes, but still define all the structs and other symbols. This is 2585prototypes, but still define all the structs and other symbols. This is

Diff Legend

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