… | |
… | |
124 | this argument. |
124 | this argument. |
125 | |
125 | |
126 | =head2 TIME REPRESENTATION |
126 | =head2 TIME REPRESENTATION |
127 | |
127 | |
128 | Libev represents time as a single floating point number, representing |
128 | Libev represents time as a single floating point number, representing |
129 | the (fractional) number of seconds since the (POSIX) epoch (in practise |
129 | the (fractional) number of seconds since the (POSIX) epoch (in practice |
130 | somewhere near the beginning of 1970, details are complicated, don't |
130 | somewhere near the beginning of 1970, details are complicated, don't |
131 | ask). This type is called C<ev_tstamp>, which is what you should use |
131 | ask). This type is called C<ev_tstamp>, which is what you should use |
132 | too. It usually aliases to the C<double> type in C. When you need to do |
132 | too. It usually aliases to the C<double> type in C. When you need to do |
133 | any calculations on it, you should treat it as some floating point value. |
133 | any calculations on it, you should treat it as some floating point value. |
134 | |
134 | |
… | |
… | |
165 | |
165 | |
166 | =item ev_tstamp ev_time () |
166 | =item ev_tstamp ev_time () |
167 | |
167 | |
168 | Returns the current time as libev would use it. Please note that the |
168 | Returns the current time as libev would use it. Please note that the |
169 | C<ev_now> function is usually faster and also often returns the timestamp |
169 | C<ev_now> function is usually faster and also often returns the timestamp |
170 | you actually want to know. |
170 | you actually want to know. Also interesting is the combination of |
|
|
171 | C<ev_update_now> and C<ev_now>. |
171 | |
172 | |
172 | =item ev_sleep (ev_tstamp interval) |
173 | =item ev_sleep (ev_tstamp interval) |
173 | |
174 | |
174 | Sleep for the given interval: The current thread will be blocked until |
175 | Sleep for the given interval: The current thread will be blocked until |
175 | either it is interrupted or the given time interval has passed. Basically |
176 | either it is interrupted or the given time interval has passed. Basically |
… | |
… | |
192 | as this indicates an incompatible change. Minor versions are usually |
193 | as this indicates an incompatible change. Minor versions are usually |
193 | compatible to older versions, so a larger minor version alone is usually |
194 | compatible to older versions, so a larger minor version alone is usually |
194 | not a problem. |
195 | not a problem. |
195 | |
196 | |
196 | Example: Make sure we haven't accidentally been linked against the wrong |
197 | Example: Make sure we haven't accidentally been linked against the wrong |
197 | version (note, however, that this will not detect ABI mismatches :). |
198 | version (note, however, that this will not detect other ABI mismatches, |
|
|
199 | such as LFS or reentrancy). |
198 | |
200 | |
199 | assert (("libev version mismatch", |
201 | assert (("libev version mismatch", |
200 | ev_version_major () == EV_VERSION_MAJOR |
202 | ev_version_major () == EV_VERSION_MAJOR |
201 | && ev_version_minor () >= EV_VERSION_MINOR)); |
203 | && ev_version_minor () >= EV_VERSION_MINOR)); |
202 | |
204 | |
… | |
… | |
213 | assert (("sorry, no epoll, no sex", |
215 | assert (("sorry, no epoll, no sex", |
214 | ev_supported_backends () & EVBACKEND_EPOLL)); |
216 | ev_supported_backends () & EVBACKEND_EPOLL)); |
215 | |
217 | |
216 | =item unsigned int ev_recommended_backends () |
218 | =item unsigned int ev_recommended_backends () |
217 | |
219 | |
218 | Return the set of all backends compiled into this binary of libev and also |
220 | Return the set of all backends compiled into this binary of libev and |
219 | recommended for this platform. This set is often smaller than the one |
221 | also recommended for this platform, meaning it will work for most file |
|
|
222 | descriptor types. This set is often smaller than the one returned by |
220 | returned by C<ev_supported_backends>, as for example kqueue is broken on |
223 | C<ev_supported_backends>, as for example kqueue is broken on most BSDs |
221 | most BSDs and will not be auto-detected unless you explicitly request it |
224 | and will not be auto-detected unless you explicitly request it (assuming |
222 | (assuming you know what you are doing). This is the set of backends that |
225 | you know what you are doing). This is the set of backends that libev will |
223 | libev will probe for if you specify no backends explicitly. |
226 | probe for if you specify no backends explicitly. |
224 | |
227 | |
225 | =item unsigned int ev_embeddable_backends () |
228 | =item unsigned int ev_embeddable_backends () |
226 | |
229 | |
227 | Returns the set of backends that are embeddable in other event loops. This |
230 | Returns the set of backends that are embeddable in other event loops. This |
228 | is the theoretical, all-platform, value. To find which backends |
231 | value is platform-specific but can include backends not available on the |
229 | might be supported on the current system, you would need to look at |
232 | current system. To find which embeddable backends might be supported on |
230 | C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for |
233 | the current system, you would need to look at C<ev_embeddable_backends () |
231 | recommended ones. |
234 | & ev_supported_backends ()>, likewise for recommended ones. |
232 | |
235 | |
233 | See the description of C<ev_embed> watchers for more info. |
236 | See the description of C<ev_embed> watchers for more info. |
234 | |
237 | |
235 | =item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] |
238 | =item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] |
236 | |
239 | |
… | |
… | |
908 | |
911 | |
909 | =item ev_invoke_pending (loop) |
912 | =item ev_invoke_pending (loop) |
910 | |
913 | |
911 | This call will simply invoke all pending watchers while resetting their |
914 | This call will simply invoke all pending watchers while resetting their |
912 | pending state. Normally, C<ev_run> does this automatically when required, |
915 | pending state. Normally, C<ev_run> does this automatically when required, |
913 | but when overriding the invoke callback this call comes handy. |
916 | but when overriding the invoke callback this call comes handy. This |
|
|
917 | function can be invoked from a watcher - this can be useful for example |
|
|
918 | when you want to do some lengthy calculation and want to pass further |
|
|
919 | event handling to another thread (you still have to make sure only one |
|
|
920 | thread executes within C<ev_invoke_pending> or C<ev_run> of course). |
914 | |
921 | |
915 | =item int ev_pending_count (loop) |
922 | =item int ev_pending_count (loop) |
916 | |
923 | |
917 | Returns the number of pending watchers - zero indicates that no watchers |
924 | Returns the number of pending watchers - zero indicates that no watchers |
918 | are pending. |
925 | are pending. |
… | |
… | |
4527 | =head3 C<kqueue> is buggy |
4534 | =head3 C<kqueue> is buggy |
4528 | |
4535 | |
4529 | The kqueue syscall is broken in all known versions - most versions support |
4536 | The kqueue syscall is broken in all known versions - most versions support |
4530 | only sockets, many support pipes. |
4537 | only sockets, many support pipes. |
4531 | |
4538 | |
4532 | Libev tries to work around this by not using C<kqueue> by default on |
4539 | Libev tries to work around this by not using C<kqueue> by default on this |
4533 | this rotten platform, but of course you can still ask for it when creating |
4540 | rotten platform, but of course you can still ask for it when creating a |
4534 | a loop. |
4541 | loop - embedding a socket-only kqueue loop into a select-based one is |
|
|
4542 | probably going to work well. |
4535 | |
4543 | |
4536 | =head3 C<poll> is buggy |
4544 | =head3 C<poll> is buggy |
4537 | |
4545 | |
4538 | Instead of fixing C<kqueue>, Apple replaced their (working) C<poll> |
4546 | Instead of fixing C<kqueue>, Apple replaced their (working) C<poll> |
4539 | implementation by something calling C<kqueue> internally around the 10.5.6 |
4547 | implementation by something calling C<kqueue> internally around the 10.5.6 |
… | |
… | |
4558 | |
4566 | |
4559 | =head3 C<errno> reentrancy |
4567 | =head3 C<errno> reentrancy |
4560 | |
4568 | |
4561 | The default compile environment on Solaris is unfortunately so |
4569 | The default compile environment on Solaris is unfortunately so |
4562 | thread-unsafe that you can't even use components/libraries compiled |
4570 | thread-unsafe that you can't even use components/libraries compiled |
4563 | without C<-D_REENTRANT> (as long as they use C<errno>), which, of course, |
4571 | without C<-D_REENTRANT> in a threaded program, which, of course, isn't |
4564 | isn't defined by default. |
4572 | defined by default. A valid, if stupid, implementation choice. |
4565 | |
4573 | |
4566 | If you want to use libev in threaded environments you have to make sure |
4574 | If you want to use libev in threaded environments you have to make sure |
4567 | it's compiled with C<_REENTRANT> defined. |
4575 | it's compiled with C<_REENTRANT> defined. |
4568 | |
4576 | |
4569 | =head3 Event port backend |
4577 | =head3 Event port backend |
4570 | |
4578 | |
4571 | The scalable event interface for Solaris is called "event ports". Unfortunately, |
4579 | The scalable event interface for Solaris is called "event |
4572 | this mechanism is very buggy. If you run into high CPU usage, your program |
4580 | ports". Unfortunately, this mechanism is very buggy in all major |
|
|
4581 | releases. If you run into high CPU usage, your program freezes or you get |
4573 | freezes or you get a large number of spurious wakeups, make sure you have |
4582 | a large number of spurious wakeups, make sure you have all the relevant |
4574 | all the relevant and latest kernel patches applied. No, I don't know which |
4583 | and latest kernel patches applied. No, I don't know which ones, but there |
4575 | ones, but there are multiple ones. |
4584 | are multiple ones to apply, and afterwards, event ports actually work |
|
|
4585 | great. |
4576 | |
4586 | |
4577 | If you can't get it to work, you can try running the program by setting |
4587 | If you can't get it to work, you can try running the program by setting |
4578 | the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and |
4588 | the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and |
4579 | C<select> backends. |
4589 | C<select> backends. |
4580 | |
4590 | |
4581 | =head2 AIX POLL BUG |
4591 | =head2 AIX POLL BUG |
4582 | |
4592 | |
4583 | AIX unfortunately has a broken C<poll.h> header. Libev works around |
4593 | AIX unfortunately has a broken C<poll.h> header. Libev works around |
4584 | this by trying to avoid the poll backend altogether (i.e. it's not even |
4594 | this by trying to avoid the poll backend altogether (i.e. it's not even |
4585 | compiled in), which normally isn't a big problem as C<select> works fine |
4595 | compiled in), which normally isn't a big problem as C<select> works fine |
4586 | with large bitsets, and AIX is dead anyway. |
4596 | with large bitsets on AIX, and AIX is dead anyway. |
4587 | |
4597 | |
4588 | =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
4598 | =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS |
4589 | |
4599 | |
4590 | =head3 General issues |
4600 | =head3 General issues |
4591 | |
4601 | |
… | |
… | |
4868 | |
4878 | |
4869 | =over 4 |
4879 | =over 4 |
4870 | |
4880 | |
4871 | =item active |
4881 | =item active |
4872 | |
4882 | |
4873 | A watcher is active as long as it has been started (has been attached to |
4883 | A watcher is active as long as it has been started and not yet stopped. |
4874 | an event loop) but not yet stopped (disassociated from the event loop). |
4884 | See L<WATCHER STATES> for details. |
4875 | |
4885 | |
4876 | =item application |
4886 | =item application |
4877 | |
4887 | |
4878 | In this document, an application is whatever is using libev. |
4888 | In this document, an application is whatever is using libev. |
|
|
4889 | |
|
|
4890 | =item backend |
|
|
4891 | |
|
|
4892 | The part of the code dealing with the operating system interfaces. |
4879 | |
4893 | |
4880 | =item callback |
4894 | =item callback |
4881 | |
4895 | |
4882 | The address of a function that is called when some event has been |
4896 | The address of a function that is called when some event has been |
4883 | detected. Callbacks are being passed the event loop, the watcher that |
4897 | detected. Callbacks are being passed the event loop, the watcher that |
4884 | received the event, and the actual event bitset. |
4898 | received the event, and the actual event bitset. |
4885 | |
4899 | |
4886 | =item callback invocation |
4900 | =item callback/watcher invocation |
4887 | |
4901 | |
4888 | The act of calling the callback associated with a watcher. |
4902 | The act of calling the callback associated with a watcher. |
4889 | |
4903 | |
4890 | =item event |
4904 | =item event |
4891 | |
4905 | |
… | |
… | |
4910 | The model used to describe how an event loop handles and processes |
4924 | The model used to describe how an event loop handles and processes |
4911 | watchers and events. |
4925 | watchers and events. |
4912 | |
4926 | |
4913 | =item pending |
4927 | =item pending |
4914 | |
4928 | |
4915 | A watcher is pending as soon as the corresponding event has been detected, |
4929 | A watcher is pending as soon as the corresponding event has been |
4916 | and stops being pending as soon as the watcher will be invoked or its |
4930 | detected. See L<WATCHER STATES> for details. |
4917 | pending status is explicitly cleared by the application. |
|
|
4918 | |
|
|
4919 | A watcher can be pending, but not active. Stopping a watcher also clears |
|
|
4920 | its pending status. |
|
|
4921 | |
4931 | |
4922 | =item real time |
4932 | =item real time |
4923 | |
4933 | |
4924 | The physical time that is observed. It is apparently strictly monotonic :) |
4934 | The physical time that is observed. It is apparently strictly monotonic :) |
4925 | |
4935 | |
… | |
… | |
4932 | =item watcher |
4942 | =item watcher |
4933 | |
4943 | |
4934 | A data structure that describes interest in certain events. Watchers need |
4944 | A data structure that describes interest in certain events. Watchers need |
4935 | to be started (attached to an event loop) before they can receive events. |
4945 | to be started (attached to an event loop) before they can receive events. |
4936 | |
4946 | |
4937 | =item watcher invocation |
|
|
4938 | |
|
|
4939 | The act of calling the callback associated with a watcher. |
|
|
4940 | |
|
|
4941 | =back |
4947 | =back |
4942 | |
4948 | |
4943 | =head1 AUTHOR |
4949 | =head1 AUTHOR |
4944 | |
4950 | |
4945 | Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. |
4951 | Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. |