… | |
… | |
247 | the current system, you would need to look at C<ev_embeddable_backends () |
247 | the 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 | |
250 | See the description of C<ev_embed> watchers for more info. |
250 | See 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 | |
254 | Sets the allocation function to use (the prototype is similar - the |
254 | Sets the allocation function to use (the prototype is similar - the |
255 | semantics are identical to the C<realloc> C89/SuS/POSIX function). It is |
255 | semantics are identical to the C<realloc> C89/SuS/POSIX function). It is |
256 | used to allocate and free memory (no surprises here). If it returns zero |
256 | used to allocate and free memory (no surprises here). If it returns zero |
257 | when memory needs to be allocated (C<size != 0>), the library might abort |
257 | when 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 | |
290 | Set the callback function to call on a retryable system call error (such |
290 | Set the callback function to call on a retryable system call error (such |
291 | as failed select, poll, epoll_wait). The message is a printable string |
291 | as failed select, poll, epoll_wait). The message is a printable string |
292 | indicating the system call or subsystem causing the problem. If this |
292 | indicating the system call or subsystem causing the problem. If this |
293 | callback is set, then libev will expect it to remedy the situation, no |
293 | callback is set, then libev will expect it to remedy the situation, no |
… | |
… | |
792 | without a previous call to C<ev_suspend>. |
792 | without a previous call to C<ev_suspend>. |
793 | |
793 | |
794 | Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the |
794 | Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the |
795 | event loop time (see C<ev_now_update>). |
795 | event loop time (see C<ev_now_update>). |
796 | |
796 | |
797 | =item ev_run (loop, int flags) |
797 | =item bool ev_run (loop, int flags) |
798 | |
798 | |
799 | Finally, this is it, the event handler. This function usually is called |
799 | Finally, this is it, the event handler. This function usually is called |
800 | after you have initialised all your watchers and you want to start |
800 | after you have initialised all your watchers and you want to start |
801 | handling events. It will ask the operating system for any new events, call |
801 | handling events. It will ask the operating system for any new events, call |
802 | the watcher callbacks, an then repeat the whole process indefinitely: This |
802 | the watcher callbacks, and then repeat the whole process indefinitely: This |
803 | is why event loops are called I<loops>. |
803 | is why event loops are called I<loops>. |
804 | |
804 | |
805 | If the flags argument is specified as C<0>, it will keep handling events |
805 | If the flags argument is specified as C<0>, it will keep handling events |
806 | until either no event watchers are active anymore or C<ev_break> was |
806 | until either no event watchers are active anymore or C<ev_break> was |
807 | called. |
807 | called. |
|
|
808 | |
|
|
809 | The return value is false if there are no more active watchers (which |
|
|
810 | usually means "all jobs done" or "deadlock"), and true in all other cases |
|
|
811 | (which usually means " you should call C<ev_run> again"). |
808 | |
812 | |
809 | Please note that an explicit C<ev_break> is usually better than |
813 | Please note that an explicit C<ev_break> is usually better than |
810 | relying on all watchers to be stopped when deciding when a program has |
814 | relying on all watchers to be stopped when deciding when a program has |
811 | finished (especially in interactive programs), but having a program |
815 | finished (especially in interactive programs), but having a program |
812 | that automatically loops as long as it has to and no longer by virtue |
816 | that automatically loops as long as it has to and no longer by virtue |
813 | of relying on its watchers stopping correctly, that is truly a thing of |
817 | of relying on its watchers stopping correctly, that is truly a thing of |
814 | beauty. |
818 | beauty. |
815 | |
819 | |
816 | This function is also I<mostly> exception-safe - you can break out of |
820 | This function is I<mostly> exception-safe - you can break out of a |
817 | a C<ev_run> call by calling C<longjmp> in a callback, throwing a C++ |
821 | C<ev_run> call by calling C<longjmp> in a callback, throwing a C++ |
818 | exception and so on. This does not decrement the C<ev_depth> value, nor |
822 | exception and so on. This does not decrement the C<ev_depth> value, nor |
819 | will it clear any outstanding C<EVBREAK_ONE> breaks. |
823 | will it clear any outstanding C<EVBREAK_ONE> breaks. |
820 | |
824 | |
821 | A flags value of C<EVRUN_NOWAIT> will look for new events, will handle |
825 | A flags value of C<EVRUN_NOWAIT> will look for new events, will handle |
822 | those events and any already outstanding ones, but will not wait and |
826 | those events and any already outstanding ones, but will not wait and |
… | |
… | |
1012 | invoke the actual watchers inside another context (another thread etc.). |
1016 | invoke the actual watchers inside another context (another thread etc.). |
1013 | |
1017 | |
1014 | If you want to reset the callback, use C<ev_invoke_pending> as new |
1018 | If you want to reset the callback, use C<ev_invoke_pending> as new |
1015 | callback. |
1019 | callback. |
1016 | |
1020 | |
1017 | =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 ()) |
1018 | |
1022 | |
1019 | Sometimes you want to share the same loop between multiple threads. This |
1023 | Sometimes you want to share the same loop between multiple threads. This |
1020 | can be done relatively simply by putting mutex_lock/unlock calls around |
1024 | can be done relatively simply by putting mutex_lock/unlock calls around |
1021 | each call to a libev function. |
1025 | each call to a libev function. |
1022 | |
1026 | |
… | |
… | |
3893 | |
3897 | |
3894 | =back |
3898 | =back |
3895 | |
3899 | |
3896 | =head1 C++ SUPPORT |
3900 | =head1 C++ SUPPORT |
3897 | |
3901 | |
|
|
3902 | =head2 C API |
|
|
3903 | |
|
|
3904 | The normal C API should work fine when used from C++: both ev.h and the |
|
|
3905 | libev sources can be compiled as C++. Therefore, code that uses the C API |
|
|
3906 | will work fine. |
|
|
3907 | |
|
|
3908 | Proper exception specifications might have to be added to callbacks passed |
|
|
3909 | to libev: exceptions may be thrown only from watcher callbacks, all |
|
|
3910 | other callbacks (allocator, syserr, loop acquire/release and periodioc |
|
|
3911 | reschedule 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 |
|
|
3913 | and 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 | |
|
|
3925 | The only API functions that can currently throw exceptions are C<ev_run>, |
|
|
3926 | C<ev_inoke>, C<ev_invoke_pending> and C<ev_loop_destroy> (the latter |
|
|
3927 | because it runs cleanup watchers). |
|
|
3928 | |
|
|
3929 | Throwing exceptions in watcher callbacks is only supported if libev itself |
|
|
3930 | is compiled with a C++ compiler or your C and C++ environments allow |
|
|
3931 | throwing exceptions through C libraries (most do). |
|
|
3932 | |
|
|
3933 | =head2 C++ API |
|
|
3934 | |
3898 | Libev comes with some simplistic wrapper classes for C++ that mainly allow |
3935 | Libev comes with some simplistic wrapper classes for C++ that mainly allow |
3899 | you to use some convenience methods to start/stop watchers and also change |
3936 | you to use some convenience methods to start/stop watchers and also change |
3900 | the callback model to a model using method callbacks on objects. |
3937 | the callback model to a model using method callbacks on objects. |
3901 | |
3938 | |
3902 | To use it, |
3939 | To use it, |
… | |
… | |
4616 | #define EV_USE_POLL 1 |
4653 | #define EV_USE_POLL 1 |
4617 | #define EV_CHILD_ENABLE 1 |
4654 | #define EV_CHILD_ENABLE 1 |
4618 | #define EV_ASYNC_ENABLE 1 |
4655 | #define EV_ASYNC_ENABLE 1 |
4619 | |
4656 | |
4620 | The actual value is a bitset, it can be a combination of the following |
4657 | The actual value is a bitset, it can be a combination of the following |
4621 | values: |
4658 | values (by default, all of these are enabled): |
4622 | |
4659 | |
4623 | =over 4 |
4660 | =over 4 |
4624 | |
4661 | |
4625 | =item C<1> - faster/larger code |
4662 | =item C<1> - faster/larger code |
4626 | |
4663 | |
… | |
… | |
4630 | code size by roughly 30% on amd64). |
4667 | code size by roughly 30% on amd64). |
4631 | |
4668 | |
4632 | When optimising for size, use of compiler flags such as C<-Os> with |
4669 | When optimising for size, use of compiler flags such as C<-Os> with |
4633 | gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of |
4670 | gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of |
4634 | assertions. |
4671 | assertions. |
|
|
4672 | |
|
|
4673 | The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler |
|
|
4674 | (e.g. gcc with C<-Os>). |
4635 | |
4675 | |
4636 | =item C<2> - faster/larger data structures |
4676 | =item C<2> - faster/larger data structures |
4637 | |
4677 | |
4638 | Replaces the small 2-heap for timer management by a faster 4-heap, larger |
4678 | Replaces the small 2-heap for timer management by a faster 4-heap, larger |
4639 | hash table sizes and so on. This will usually further increase code size |
4679 | hash table sizes and so on. This will usually further increase code size |
4640 | and can additionally have an effect on the size of data structures at |
4680 | and can additionally have an effect on the size of data structures at |
4641 | runtime. |
4681 | runtime. |
|
|
4682 | |
|
|
4683 | The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler |
|
|
4684 | (e.g. gcc with C<-Os>). |
4642 | |
4685 | |
4643 | =item C<4> - full API configuration |
4686 | =item C<4> - full API configuration |
4644 | |
4687 | |
4645 | This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and |
4688 | This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and |
4646 | enables multiplicity (C<EV_MULTIPLICITY>=1). |
4689 | enables multiplicity (C<EV_MULTIPLICITY>=1). |