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

Comparing libev/ev.pod (file contents):
Revision 1.400 by root, Mon Apr 2 23:46:11 2012 UTC vs.
Revision 1.403 by sf-exg, Wed Apr 18 06:56:53 2012 UTC

… …
247the current system, you would need to look at C<ev_embeddable_backends () 247the current system, you would need to look at C<ev_embeddable_backends ()
248& ev_supported_backends ()>, likewise for recommended ones. 248& ev_supported_backends ()>, likewise for recommended ones.
249 249
250See the description of C<ev_embed> watchers for more info. 250See the description of C<ev_embed> watchers for more info.
251 251
252=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 252=item ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())
253 253
254Sets the allocation function to use (the prototype is similar - the 254Sets the allocation function to use (the prototype is similar - the
255semantics are identical to the C<realloc> C89/SuS/POSIX function). It is 255semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
256used to allocate and free memory (no surprises here). If it returns zero 256used to allocate and free memory (no surprises here). If it returns zero
257when memory needs to be allocated (C<size != 0>), the library might abort 257when memory needs to be allocated (C<size != 0>), the library might abort
… …
283 } 283 }
284 284
285 ... 285 ...
286 ev_set_allocator (persistent_realloc); 286 ev_set_allocator (persistent_realloc);
287 287
288=item ev_set_syserr_cb (void (*cb)(const char *msg)) 288=item ev_set_syserr_cb (void (*cb)(const char *msg) throw ())
289 289
290Set the callback function to call on a retryable system call error (such 290Set the callback function to call on a retryable system call error (such
291as failed select, poll, epoll_wait). The message is a printable string 291as failed select, poll, epoll_wait). The message is a printable string
292indicating the system call or subsystem causing the problem. If this 292indicating the system call or subsystem causing the problem. If this
293callback is set, then libev will expect it to remedy the situation, no 293callback is set, then libev will expect it to remedy the situation, no
… …
1016invoke the actual watchers inside another context (another thread etc.). 1016invoke the actual watchers inside another context (another thread etc.).
1017 1017
1018If you want to reset the callback, use C<ev_invoke_pending> as new 1018If you want to reset the callback, use C<ev_invoke_pending> as new
1019callback. 1019callback.
1020 1020
1021=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P)) 1021=item ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())
1022 1022
1023Sometimes you want to share the same loop between multiple threads. This 1023Sometimes you want to share the same loop between multiple threads. This
1024can be done relatively simply by putting mutex_lock/unlock calls around 1024can be done relatively simply by putting mutex_lock/unlock calls around
1025each call to a libev function. 1025each call to a libev function.
1026 1026
… …
1874 callback (EV_P_ ev_timer *w, int revents) 1874 callback (EV_P_ ev_timer *w, int revents)
1875 { 1875 {
1876 // calculate when the timeout would happen 1876 // calculate when the timeout would happen
1877 ev_tstamp after = last_activity - ev_now (EV_A) + timeout; 1877 ev_tstamp after = last_activity - ev_now (EV_A) + timeout;
1878 1878
1879 // if negative, it means we the timeout already occured 1879 // if negative, it means we the timeout already occurred
1880 if (after < 0.) 1880 if (after < 0.)
1881 { 1881 {
1882 // timeout occurred, take action 1882 // timeout occurred, take action
1883 } 1883 }
1884 else 1884 else
… …
1902 1902
1903Otherwise, we now the earliest time at which the timeout would trigger, 1903Otherwise, we now the earliest time at which the timeout would trigger,
1904and simply start the timer with this timeout value. 1904and simply start the timer with this timeout value.
1905 1905
1906In other words, each time the callback is invoked it will check whether 1906In other words, each time the callback is invoked it will check whether
1907the timeout cocured. If not, it will simply reschedule itself to check 1907the timeout occurred. If not, it will simply reschedule itself to check
1908again at the earliest time it could time out. Rinse. Repeat. 1908again at the earliest time it could time out. Rinse. Repeat.
1909 1909
1910This scheme causes more callback invocations (about one every 60 seconds 1910This scheme causes more callback invocations (about one every 60 seconds
1911minus half the average time between activity), but virtually no calls to 1911minus half the average time between activity), but virtually no calls to
1912libev to change the timeout. 1912libev to change the timeout.
… …
1926 if (activity detected) 1926 if (activity detected)
1927 last_activity = ev_now (EV_A); 1927 last_activity = ev_now (EV_A);
1928 1928
1929When your timeout value changes, then the timeout can be changed by simply 1929When your timeout value changes, then the timeout can be changed by simply
1930providing a new value, stopping the timer and calling the callback, which 1930providing a new value, stopping the timer and calling the callback, which
1931will agaion do the right thing (for example, time out immediately :). 1931will again do the right thing (for example, time out immediately :).
1932 1932
1933 timeout = new_value; 1933 timeout = new_value;
1934 ev_timer_stop (EV_A_ &timer); 1934 ev_timer_stop (EV_A_ &timer);
1935 callback (EV_A_ &timer, 0); 1935 callback (EV_A_ &timer, 0);
1936 1936
… …
3897 3897
3898=back 3898=back
3899 3899
3900=head1 C++ SUPPORT 3900=head1 C++ SUPPORT
3901 3901
3902=head2 C API
3903
3904The normal C API should work fine when used from C++: both ev.h and the
3905libev sources can be compiled as C++. Therefore, code that uses the C API
3906will work fine.
3907
3908Proper exception specifications might have to be added to callbacks passed
3909to libev: exceptions may be thrown only from watcher callbacks, all
3910other callbacks (allocator, syserr, loop acquire/release and periodioc
3911reschedule callbacks) must not throw exceptions, and might need a C<throw
3912()> specification. If you have code that needs to be compiled as both C
3913and C++ you can use the C<EV_THROW> macro for this:
3914
3915 static void
3916 fatal_error (const char *msg) EV_THROW
3917 {
3918 perror (msg);
3919 abort ();
3920 }
3921
3922 ...
3923 ev_set_syserr_cb (fatal_error);
3924
3925The only API functions that can currently throw exceptions are C<ev_run>,
3926C<ev_invoke>, C<ev_invoke_pending> and C<ev_loop_destroy> (the latter
3927because it runs cleanup watchers).
3928
3929Throwing exceptions in watcher callbacks is only supported if libev itself
3930is compiled with a C++ compiler or your C and C++ environments allow
3931throwing exceptions through C libraries (most do).
3932
3933=head2 C++ API
3934
3902Libev comes with some simplistic wrapper classes for C++ that mainly allow 3935Libev comes with some simplistic wrapper classes for C++ that mainly allow
3903you to use some convenience methods to start/stop watchers and also change 3936you to use some convenience methods to start/stop watchers and also change
3904the callback model to a model using method callbacks on objects. 3937the callback model to a model using method callbacks on objects.
3905 3938
3906To use it, 3939To use it,

Diff Legend

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