… | |
… | |
675 | and is not embeddable, which would limit the usefulness of this backend |
675 | and is not embeddable, which would limit the usefulness of this backend |
676 | immensely. |
676 | immensely. |
677 | |
677 | |
678 | =item C<EVBACKEND_PORT> (value 32, Solaris 10) |
678 | =item C<EVBACKEND_PORT> (value 32, Solaris 10) |
679 | |
679 | |
680 | This uses the Solaris 10 event port mechanism. As with everything on Solaris, |
680 | This uses the Solaris 10 event port mechanism. As with everything on |
681 | it's really slow, but it still scales very well (O(active_fds)). |
681 | Solaris, it's really slow, but it still scales very well (O(active_fds)). |
682 | |
682 | |
683 | While this backend scales well, it requires one system call per active |
683 | While this backend scales well, it requires one system call per active |
684 | file descriptor per loop iteration. For small and medium numbers of file |
684 | file descriptor per loop iteration. For small and medium numbers of file |
685 | descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend |
685 | descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend |
686 | might perform better. |
686 | might perform better. |
… | |
… | |
959 | - Queue all expired timers. |
959 | - Queue all expired timers. |
960 | - Queue all expired periodics. |
960 | - Queue all expired periodics. |
961 | - Queue all idle watchers with priority higher than that of pending events. |
961 | - Queue all idle watchers with priority higher than that of pending events. |
962 | - Queue all check watchers. |
962 | - Queue all check watchers. |
963 | - Call all queued watchers in reverse order (i.e. check watchers first). |
963 | - Call all queued watchers in reverse order (i.e. check watchers first). |
964 | Signals and child watchers are implemented as I/O watchers, and will |
964 | Signals, async and child watchers are implemented as I/O watchers, and |
965 | be handled here by queueing them when their watcher gets executed. |
965 | will be handled here by queueing them when their watcher gets executed. |
966 | - If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT |
966 | - If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT |
967 | were used, or there are no active watchers, goto FINISH, otherwise |
967 | were used, or there are no active watchers, goto FINISH, otherwise |
968 | continue with step LOOP. |
968 | continue with step LOOP. |
969 | FINISH: |
969 | FINISH: |
970 | - Reset the ev_break status iff it was EVBREAK_ONE. |
970 | - Reset the ev_break status iff it was EVBREAK_ONE. |
… | |
… | |
1396 | |
1396 | |
1397 | =item bool ev_is_active (ev_TYPE *watcher) |
1397 | =item bool ev_is_active (ev_TYPE *watcher) |
1398 | |
1398 | |
1399 | Returns a true value iff the watcher is active (i.e. it has been started |
1399 | Returns a true value iff the watcher is active (i.e. it has been started |
1400 | and not yet been stopped). As long as a watcher is active you must not modify |
1400 | and not yet been stopped). As long as a watcher is active you must not modify |
1401 | it. |
1401 | it unless documented otherwise. |
|
|
1402 | |
|
|
1403 | Obviously, it is safe to call this on an active watcher, or actually any |
|
|
1404 | watcher that is initialised. |
1402 | |
1405 | |
1403 | =item bool ev_is_pending (ev_TYPE *watcher) |
1406 | =item bool ev_is_pending (ev_TYPE *watcher) |
1404 | |
1407 | |
1405 | Returns a true value iff the watcher is pending, (i.e. it has outstanding |
1408 | Returns a true value iff the watcher is pending, (i.e. it has outstanding |
1406 | events but its callback has not yet been invoked). As long as a watcher |
1409 | events but its callback has not yet been invoked). As long as a watcher |
1407 | is pending (but not active) you must not call an init function on it (but |
1410 | is pending (but not active) you must not call an init function on it (but |
1408 | C<ev_TYPE_set> is safe), you must not change its priority, and you must |
1411 | C<ev_TYPE_set> is safe), you must not change its priority, and you must |
1409 | make sure the watcher is available to libev (e.g. you cannot C<free ()> |
1412 | make sure the watcher is available to libev (e.g. you cannot C<free ()> |
1410 | it). |
1413 | it). |
1411 | |
1414 | |
|
|
1415 | It is safe to call this on any watcher in any state as long as it is |
|
|
1416 | initialised. |
|
|
1417 | |
1412 | =item callback ev_cb (ev_TYPE *watcher) |
1418 | =item callback ev_cb (ev_TYPE *watcher) |
1413 | |
1419 | |
1414 | Returns the callback currently set on the watcher. |
1420 | Returns the callback currently set on the watcher. |
1415 | |
1421 | |
1416 | =item ev_set_cb (ev_TYPE *watcher, callback) |
1422 | =item ev_set_cb (ev_TYPE *watcher, callback) |
… | |
… | |
1429 | from being executed (except for C<ev_idle> watchers). |
1435 | from being executed (except for C<ev_idle> watchers). |
1430 | |
1436 | |
1431 | If you need to suppress invocation when higher priority events are pending |
1437 | If you need to suppress invocation when higher priority events are pending |
1432 | you need to look at C<ev_idle> watchers, which provide this functionality. |
1438 | you need to look at C<ev_idle> watchers, which provide this functionality. |
1433 | |
1439 | |
1434 | You I<must not> change the priority of a watcher as long as it is active or |
1440 | You I<must not> change the priority of a watcher as long as it is active |
1435 | pending. |
1441 | or pending. Reading the priority with C<ev_priority> is fine in any state. |
1436 | |
1442 | |
1437 | Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is |
1443 | Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is |
1438 | fine, as long as you do not mind that the priority value you query might |
1444 | fine, as long as you do not mind that the priority value you query might |
1439 | or might not have been clamped to the valid range. |
1445 | or might not have been clamped to the valid range. |
1440 | |
1446 | |
… | |
… | |
1462 | |
1468 | |
1463 | =item ev_feed_event (loop, ev_TYPE *watcher, int revents) |
1469 | =item ev_feed_event (loop, ev_TYPE *watcher, int revents) |
1464 | |
1470 | |
1465 | Feeds the given event set into the event loop, as if the specified event |
1471 | Feeds the given event set into the event loop, as if the specified event |
1466 | had happened for the specified watcher (which must be a pointer to an |
1472 | had happened for the specified watcher (which must be a pointer to an |
1467 | initialised but not necessarily started event watcher). Obviously you must |
1473 | initialised but not necessarily started event watcher, though it can be |
1468 | not free the watcher as long as it has pending events. |
1474 | active). Obviously you must not free the watcher as long as it has pending |
|
|
1475 | events. |
1469 | |
1476 | |
1470 | Stopping the watcher, letting libev invoke it, or calling |
1477 | Stopping the watcher, letting libev invoke it, or calling |
1471 | C<ev_clear_pending> will clear the pending event, even if the watcher was |
1478 | C<ev_clear_pending> will clear the pending event, even if the watcher was |
1472 | not started in the first place. |
1479 | not started in the first place. |
1473 | |
1480 | |
… | |
… | |
1501 | |
1508 | |
1502 | =item started/running/active |
1509 | =item started/running/active |
1503 | |
1510 | |
1504 | Once a watcher has been started with a call to C<ev_TYPE_start> it becomes |
1511 | Once a watcher has been started with a call to C<ev_TYPE_start> it becomes |
1505 | property of the event loop, and is actively waiting for events. While in |
1512 | property of the event loop, and is actively waiting for events. While in |
1506 | this state it cannot be accessed (except in a few documented ways), moved, |
1513 | this state it cannot be accessed (except in a few documented ways, such as |
1507 | freed or anything else - the only legal thing is to keep a pointer to it, |
1514 | stoping it), moved, freed or anything else - the only legal thing is to |
1508 | and call libev functions on it that are documented to work on active watchers. |
1515 | keep a pointer to it, and call libev functions on it that are documented |
|
|
1516 | to work on active watchers. |
|
|
1517 | |
|
|
1518 | As a rule of thumb, before accessing a member or calling any function on |
|
|
1519 | a watcher, it should be stopped (or freshly initialised). If that is not |
|
|
1520 | convenient, you can check the documentation for that function or member to |
|
|
1521 | see if it is safe to use on an active watcher. |
1509 | |
1522 | |
1510 | =item pending |
1523 | =item pending |
1511 | |
1524 | |
1512 | If a watcher is active and libev determines that an event it is interested |
1525 | If a watcher is active and libev determines that an event it is interested |
1513 | in has occurred (such as a timer expiring), it will become pending. It will |
1526 | in has occurred (such as a timer expiring), it will become pending. It |
1514 | stay in this pending state until either it is stopped or its callback is |
1527 | will stay in this pending state until either it is explicitly stopped or |
1515 | about to be invoked, so it is not normally pending inside the watcher |
1528 | its callback is about to be invoked, so it is not normally pending inside |
1516 | callback. |
1529 | the watcher callback. |
1517 | |
1530 | |
1518 | The watcher might or might not be active while it is pending (for example, |
1531 | Generally, the watcher might or might not be active while it is pending |
1519 | an expired non-repeating timer can be pending but no longer active). If it |
1532 | (for example, an expired non-repeating timer can be pending but no longer |
1520 | is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>), |
1533 | active). If it is pending but not active, it can be freely accessed (e.g. |
1521 | but it is still property of the event loop at this time, so cannot be |
1534 | by calling C<ev_TYPE_set>), but it is still property of the event loop at |
1522 | moved, freed or reused. And if it is active the rules described in the |
1535 | this time, so cannot be moved, freed or reused. And if it is active the |
1523 | previous item still apply. |
1536 | rules described in the previous item still apply. |
|
|
1537 | |
|
|
1538 | Explicitly stopping a watcher will also clear the pending state |
|
|
1539 | unconditionally, so it is safe to stop a watcher and then free it. |
1524 | |
1540 | |
1525 | It is also possible to feed an event on a watcher that is not active (e.g. |
1541 | It is also possible to feed an event on a watcher that is not active (e.g. |
1526 | via C<ev_feed_event>), in which case it becomes pending without being |
1542 | via C<ev_feed_event>), in which case it becomes pending without being |
1527 | active. |
1543 | active. |
1528 | |
1544 | |
… | |
… | |
3862 | event loop thread and an unspecified mechanism to wake up the main thread. |
3878 | event loop thread and an unspecified mechanism to wake up the main thread. |
3863 | |
3879 | |
3864 | First, you need to associate some data with the event loop: |
3880 | First, you need to associate some data with the event loop: |
3865 | |
3881 | |
3866 | typedef struct { |
3882 | typedef struct { |
3867 | mutex_t lock; /* global loop lock */ |
3883 | pthread_mutex_t lock; /* global loop lock */ |
|
|
3884 | pthread_t tid; |
|
|
3885 | pthread_cond_t invoke_cv; |
3868 | ev_async async_w; |
3886 | ev_async async_w; |
3869 | thread_t tid; |
|
|
3870 | cond_t invoke_cv; |
|
|
3871 | } userdata; |
3887 | } userdata; |
3872 | |
3888 | |
3873 | void prepare_loop (EV_P) |
3889 | void prepare_loop (EV_P) |
3874 | { |
3890 | { |
3875 | // for simplicity, we use a static userdata struct. |
3891 | // for simplicity, we use a static userdata struct. |
3876 | static userdata u; |
3892 | static userdata u; |
3877 | |
3893 | |
3878 | ev_async_init (&u->async_w, async_cb); |
3894 | ev_async_init (&u.async_w, async_cb); |
3879 | ev_async_start (EV_A_ &u->async_w); |
3895 | ev_async_start (EV_A_ &u.async_w); |
3880 | |
3896 | |
3881 | pthread_mutex_init (&u->lock, 0); |
3897 | pthread_mutex_init (&u.lock, 0); |
3882 | pthread_cond_init (&u->invoke_cv, 0); |
3898 | pthread_cond_init (&u.invoke_cv, 0); |
3883 | |
3899 | |
3884 | // now associate this with the loop |
3900 | // now associate this with the loop |
3885 | ev_set_userdata (EV_A_ u); |
3901 | ev_set_userdata (EV_A_ &u); |
3886 | ev_set_invoke_pending_cb (EV_A_ l_invoke); |
3902 | ev_set_invoke_pending_cb (EV_A_ l_invoke); |
3887 | ev_set_loop_release_cb (EV_A_ l_release, l_acquire); |
3903 | ev_set_loop_release_cb (EV_A_ l_release, l_acquire); |
3888 | |
3904 | |
3889 | // then create the thread running ev_run |
3905 | // then create the thread running ev_run |
3890 | pthread_create (&u->tid, 0, l_run, EV_A); |
3906 | pthread_create (&u.tid, 0, l_run, EV_A); |
3891 | } |
3907 | } |
3892 | |
3908 | |
3893 | The callback for the C<ev_async> watcher does nothing: the watcher is used |
3909 | The callback for the C<ev_async> watcher does nothing: the watcher is used |
3894 | solely to wake up the event loop so it takes notice of any new watchers |
3910 | solely to wake up the event loop so it takes notice of any new watchers |
3895 | that might have been added: |
3911 | that might have been added: |
… | |
… | |
4268 | |
4284 | |
4269 | For C<ev::embed> watchers this method is called C<set_embed>, to avoid |
4285 | For C<ev::embed> watchers this method is called C<set_embed>, to avoid |
4270 | clashing with the C<set (loop)> method. |
4286 | clashing with the C<set (loop)> method. |
4271 | |
4287 | |
4272 | For C<ev::io> watchers there is an additional C<set> method that acepts a |
4288 | For C<ev::io> watchers there is an additional C<set> method that acepts a |
4273 | new event mask only, and internally calls C<ev_io_modfify>. |
4289 | new event mask only, and internally calls C<ev_io_modify>. |
4274 | |
4290 | |
4275 | =item w->start () |
4291 | =item w->start () |
4276 | |
4292 | |
4277 | Starts the watcher. Note that there is no C<loop> argument, as the |
4293 | Starts the watcher. Note that there is no C<loop> argument, as the |
4278 | constructor already stores the event loop. |
4294 | constructor already stores the event loop. |