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

Comparing libev/ev.pod (file contents):
Revision 1.326 by root, Sun Oct 24 19:44:27 2010 UTC vs.
Revision 1.334 by root, Mon Oct 25 10:30:23 2010 UTC

… …
77on event-based programming, nor will it introduce event-based programming 77on event-based programming, nor will it introduce event-based programming
78with libev. 78with libev.
79 79
80Familiarity with event based programming techniques in general is assumed 80Familiarity with event based programming techniques in general is assumed
81throughout this document. 81throughout this document.
82
83=head1 WHAT TO READ WHEN IN A HURRY
84
85This manual tries to be very detailed, but unfortunately, this also makes
86it very long. If you just want to know the basics of libev, I suggest
87reading L<ANATOMY OF A WATCHER>, then the L<EXAMPLE PROGRAM> above and
88look up the missing functions in L<GLOBAL FUNCTIONS> and the C<ev_io> and
89C<ev_timer> sections in L<WATCHER TYPES>.
82 90
83=head1 ABOUT LIBEV 91=head1 ABOUT LIBEV
84 92
85Libev is an event loop: you register interest in certain events (such as a 93Libev is an event loop: you register interest in certain events (such as a
86file descriptor being readable or a timeout occurring), and it will manage 94file descriptor being readable or a timeout occurring), and it will manage
… …
300An event loop is described by a C<struct ev_loop *> (the C<struct> is 308An event loop is described by a C<struct ev_loop *> (the C<struct> is
301I<not> optional in this case unless libev 3 compatibility is disabled, as 309I<not> optional in this case unless libev 3 compatibility is disabled, as
302libev 3 had an C<ev_loop> function colliding with the struct name). 310libev 3 had an C<ev_loop> function colliding with the struct name).
303 311
304The library knows two types of such loops, the I<default> loop, which 312The library knows two types of such loops, the I<default> loop, which
305supports signals and child events, and dynamically created event loops 313supports child process events, and dynamically created event loops which
306which do not. 314do not.
307 315
308=over 4 316=over 4
309 317
310=item struct ev_loop *ev_default_loop (unsigned int flags) 318=item struct ev_loop *ev_default_loop (unsigned int flags)
311 319
… …
1114The event loop has been resumed in the child process after fork (see 1122The event loop has been resumed in the child process after fork (see
1115C<ev_fork>). 1123C<ev_fork>).
1116 1124
1117=item C<EV_CLEANUP> 1125=item C<EV_CLEANUP>
1118 1126
1119The event loop is abotu to be destroyed (see C<ev_cleanup>). 1127The event loop is about to be destroyed (see C<ev_cleanup>).
1120 1128
1121=item C<EV_ASYNC> 1129=item C<EV_ASYNC>
1122 1130
1123The given async watcher has been asynchronously notified (see C<ev_async>). 1131The given async watcher has been asynchronously notified (see C<ev_async>).
1124 1132
… …
3098 3106
3099=item ev_fork_init (ev_fork *, callback) 3107=item ev_fork_init (ev_fork *, callback)
3100 3108
3101Initialises and configures the fork watcher - it has no parameters of any 3109Initialises and configures the fork watcher - it has no parameters of any
3102kind. There is a C<ev_fork_set> macro, but using it is utterly pointless, 3110kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
3103believe me. 3111really.
3104 3112
3105=back 3113=back
3106 3114
3107 3115
3108=head2 C<ev_cleanup> - even the best things end 3116=head2 C<ev_cleanup> - even the best things end
3109 3117
3110Cleanup watchers are called just before the event loop they are registered 3118Cleanup watchers are called just before the event loop is being destroyed
3111with is being destroyed. 3119by a call to C<ev_loop_destroy>.
3112 3120
3113While there is no guarantee that the event loop gets destroyed, cleanup 3121While there is no guarantee that the event loop gets destroyed, cleanup
3114watchers provide a convenient method to install cleanup hooks for your 3122watchers provide a convenient method to install cleanup hooks for your
3115program, worker threads and so on - you just to make sure to destroy the 3123program, worker threads and so on - you just to make sure to destroy the
3116loop when you want them to be invoked. 3124loop when you want them to be invoked.
3117 3125
3126Cleanup watchers are invoked in the same way as any other watcher. Unlike
3127all other watchers, they do not keep a reference to the event loop (which
3128makes a lot of sense if you think about it). Like all other watchers, you
3129can call libev functions in the callback, except C<ev_cleanup_start>.
3130
3118=head3 Watcher-Specific Functions and Data Members 3131=head3 Watcher-Specific Functions and Data Members
3119 3132
3120=over 4 3133=over 4
3121 3134
3122=item ev_cleanup_init (ev_cleanup *, callback) 3135=item ev_cleanup_init (ev_cleanup *, callback)
3123 3136
3124Initialises and configures the cleanup watcher - it has no parameters of 3137Initialises and configures the cleanup watcher - it has no parameters of
3125any kind. There is a C<ev_cleanup_set> macro, but using it is utterly 3138any kind. There is a C<ev_cleanup_set> macro, but using it is utterly
3126pointless, believe me. 3139pointless, I assure you.
3127 3140
3128=back 3141=back
3129 3142
3130Example: Register an atexit handler to destroy the default loop, so any 3143Example: Register an atexit handler to destroy the default loop, so any
3131cleanup functions are called. 3144cleanup functions are called.
… …
4752structure (guaranteed by POSIX but not by ISO C for example), but it also 4765structure (guaranteed by POSIX but not by ISO C for example), but it also
4753assumes that the same (machine) code can be used to call any watcher 4766assumes that the same (machine) code can be used to call any watcher
4754callback: The watcher callbacks have different type signatures, but libev 4767callback: The watcher callbacks have different type signatures, but libev
4755calls them using an C<ev_watcher *> internally. 4768calls them using an C<ev_watcher *> internally.
4756 4769
4770=item pointer accesses must be thread-atomic
4771
4772Accessing a pointer value must be atomic, it must both be readable and
4773writable in one piece - this is the case on all current architectures.
4774
4757=item C<sig_atomic_t volatile> must be thread-atomic as well 4775=item C<sig_atomic_t volatile> must be thread-atomic as well
4758 4776
4759The type C<sig_atomic_t volatile> (or whatever is defined as 4777The type C<sig_atomic_t volatile> (or whatever is defined as
4760C<EV_ATOMIC_T>) must be atomic with respect to accesses from different 4778C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
4761threads. This is not part of the specification for C<sig_atomic_t>, but is 4779threads. This is not part of the specification for C<sig_atomic_t>, but is
… …
4867=back 4885=back
4868 4886
4869 4887
4870=head1 PORTING FROM LIBEV 3.X TO 4.X 4888=head1 PORTING FROM LIBEV 3.X TO 4.X
4871 4889
4872The major version 4 introduced some minor incompatible changes to the API. 4890The major version 4 introduced some incompatible changes to the API.
4873 4891
4874At the moment, the C<ev.h> header file tries to implement superficial 4892At the moment, the C<ev.h> header file provides compatibility definitions
4875compatibility, so most programs should still compile. Those might be 4893for all changes, so most programs should still compile. The compatibility
4876removed in later versions of libev, so better update early than late. 4894layer might be removed in later versions of libev, so better update to the
4895new API early than late.
4877 4896
4878=over 4 4897=over 4
4898
4899=item C<EV_COMPAT3> backwards compatibility mechanism
4900
4901The backward compatibility mechanism can be controlled by
4902C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
4903section.
4879 4904
4880=item C<ev_default_destroy> and C<ev_default_fork> have been removed 4905=item C<ev_default_destroy> and C<ev_default_fork> have been removed
4881 4906
4882These calls can be replaced easily by their C<ev_loop_xxx> counterparts: 4907These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
4883 4908
… …
4909ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme 4934ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
4910as all other watcher types. Note that C<ev_loop_fork> is still called 4935as all other watcher types. Note that C<ev_loop_fork> is still called
4911C<ev_loop_fork> because it would otherwise clash with the C<ev_fork> 4936C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
4912typedef. 4937typedef.
4913 4938
4914=item C<EV_COMPAT3> backwards compatibility mechanism
4915
4916The backward compatibility mechanism can be controlled by
4917C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
4918section.
4919
4920=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES> 4939=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4921 4940
4922The preprocessor symbol C<EV_MINIMAL> has been replaced by a different 4941The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4923mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile 4942mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4924and work, but the library code will of course be larger. 4943and work, but the library code will of course be larger.
… …
4998 5017
4999=back 5018=back
5000 5019
5001=head1 AUTHOR 5020=head1 AUTHOR
5002 5021
5003Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 5022Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
5023Magnusson and Emanuele Giaquinta.
5004 5024

Diff Legend

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