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

Comparing libev/ev.pod (file contents):
Revision 1.460 by root, Wed Jan 22 02:00:13 2020 UTC vs.
Revision 1.466 by root, Mon Jun 8 11:15:59 2020 UTC

… …
1396 1396
1397=item bool ev_is_active (ev_TYPE *watcher) 1397=item bool ev_is_active (ev_TYPE *watcher)
1398 1398
1399Returns a true value iff the watcher is active (i.e. it has been started 1399Returns a true value iff the watcher is active (i.e. it has been started
1400and not yet been stopped). As long as a watcher is active you must not modify 1400and not yet been stopped). As long as a watcher is active you must not modify
1401it. 1401it unless documented otherwise.
1402 1402
1403=item bool ev_is_pending (ev_TYPE *watcher) 1403=item bool ev_is_pending (ev_TYPE *watcher)
1404 1404
1405Returns a true value iff the watcher is pending, (i.e. it has outstanding 1405Returns a true value iff the watcher is pending, (i.e. it has outstanding
1406events but its callback has not yet been invoked). As long as a watcher 1406events but its callback has not yet been invoked). As long as a watcher
… …
1653 1653
1654Most members are additionally marked with either I<[read-only]>, meaning 1654Most members are additionally marked with either I<[read-only]>, meaning
1655that, while the watcher is active, you can look at the member and expect 1655that, while the watcher is active, you can look at the member and expect
1656some sensible content, but you must not modify it (you can modify it while 1656some sensible content, but you must not modify it (you can modify it while
1657the watcher is stopped to your hearts content), or I<[read-write]>, which 1657the watcher is stopped to your hearts content), or I<[read-write]>, which
1658means you can expect it to have some sensible content while the watcher 1658means you can expect it to have some sensible content while the watcher is
1659is active, but you can also modify it. Modifying it may not do something 1659active, but you can also modify it (within the same thread as the event
1660loop, i.e. without creating data races). Modifying it may not do something
1660sensible or take immediate effect (or do anything at all), but libev will 1661sensible or take immediate effect (or do anything at all), but libev will
1661not crash or malfunction in any way. 1662not crash or malfunction in any way.
1662 1663
1663In any case, the documentation for each member will explain what the 1664In any case, the documentation for each member will explain what the
1664effects are, and if there are any additional access restrictions. 1665effects are, and if there are any additional access restrictions.
… …
1829=item ev_io_init (ev_io *, callback, int fd, int events) 1830=item ev_io_init (ev_io *, callback, int fd, int events)
1830 1831
1831=item ev_io_set (ev_io *, int fd, int events) 1832=item ev_io_set (ev_io *, int fd, int events)
1832 1833
1833Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1834Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1834receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or 1835receive events for and C<events> is either C<EV_READ>, C<EV_WRITE>, both
1835C<EV_READ | EV_WRITE>, to express the desire to receive the given events. 1836C<EV_READ | EV_WRITE> or C<0>, to express the desire to receive the given
1837events.
1838
1839Note that setting the C<events> to C<0> and starting the watcher is
1840supported, but not specially optimized - if your program sometimes happens
1841to generate this combination this is fine, but if it is easy to avoid
1842starting an io watcher watching for no events you should do so.
1836 1843
1837=item ev_io_modify (ev_io *, int events) 1844=item ev_io_modify (ev_io *, int events)
1838 1845
1839Similar to C<ev_io_set>, but only changes the event mask. Using this might 1846Similar to C<ev_io_set>, but only changes the requested events. Using this
1840be faster with some backends, as libev can assume that the C<fd> still 1847might be faster with some backends, as libev can assume that the C<fd>
1841refers to the same underlying file description, something it cannot do 1848still refers to the same underlying file description, something it cannot
1842when using C<ev_io_set>. 1849do when using C<ev_io_set>.
1843 1850
1844=item int fd [no-modify] 1851=item int fd [no-modify]
1845 1852
1846The file descriptor being watched. While it can be read at any time, you 1853The file descriptor being watched. While it can be read at any time, you
1847must not modify this member even when the watcher is stopped - always use 1854must not modify this member even when the watcher is stopped - always use
… …
3855event loop thread and an unspecified mechanism to wake up the main thread. 3862event loop thread and an unspecified mechanism to wake up the main thread.
3856 3863
3857First, you need to associate some data with the event loop: 3864First, you need to associate some data with the event loop:
3858 3865
3859 typedef struct { 3866 typedef struct {
3860 mutex_t lock; /* global loop lock */ 3867 pthread_mutex_t lock; /* global loop lock */
3868 pthread_t tid;
3869 pthread_cond_t invoke_cv;
3861 ev_async async_w; 3870 ev_async async_w;
3862 thread_t tid;
3863 cond_t invoke_cv;
3864 } userdata; 3871 } userdata;
3865 3872
3866 void prepare_loop (EV_P) 3873 void prepare_loop (EV_P)
3867 { 3874 {
3868 // for simplicity, we use a static userdata struct. 3875 // for simplicity, we use a static userdata struct.
3869 static userdata u; 3876 static userdata u;
3870 3877
3871 ev_async_init (&u->async_w, async_cb); 3878 ev_async_init (&u.async_w, async_cb);
3872 ev_async_start (EV_A_ &u->async_w); 3879 ev_async_start (EV_A_ &u.async_w);
3873 3880
3874 pthread_mutex_init (&u->lock, 0); 3881 pthread_mutex_init (&u.lock, 0);
3875 pthread_cond_init (&u->invoke_cv, 0); 3882 pthread_cond_init (&u.invoke_cv, 0);
3876 3883
3877 // now associate this with the loop 3884 // now associate this with the loop
3878 ev_set_userdata (EV_A_ u); 3885 ev_set_userdata (EV_A_ &u);
3879 ev_set_invoke_pending_cb (EV_A_ l_invoke); 3886 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3880 ev_set_loop_release_cb (EV_A_ l_release, l_acquire); 3887 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3881 3888
3882 // then create the thread running ev_run 3889 // then create the thread running ev_run
3883 pthread_create (&u->tid, 0, l_run, EV_A); 3890 pthread_create (&u.tid, 0, l_run, EV_A);
3884 } 3891 }
3885 3892
3886The callback for the C<ev_async> watcher does nothing: the watcher is used 3893The callback for the C<ev_async> watcher does nothing: the watcher is used
3887solely to wake up the event loop so it takes notice of any new watchers 3894solely to wake up the event loop so it takes notice of any new watchers
3888that might have been added: 3895that might have been added:
… …
4259gets automatically stopped and restarted when reconfiguring it with this 4266gets automatically stopped and restarted when reconfiguring it with this
4260method. 4267method.
4261 4268
4262For C<ev::embed> watchers this method is called C<set_embed>, to avoid 4269For C<ev::embed> watchers this method is called C<set_embed>, to avoid
4263clashing with the C<set (loop)> method. 4270clashing with the C<set (loop)> method.
4271
4272For C<ev::io> watchers there is an additional C<set> method that acepts a
4273new event mask only, and internally calls C<ev_io_modfify>.
4264 4274
4265=item w->start () 4275=item w->start ()
4266 4276
4267Starts the watcher. Note that there is no C<loop> argument, as the 4277Starts the watcher. Note that there is no C<loop> argument, as the
4268constructor already stores the event loop. 4278constructor already stores the event loop.

Diff Legend

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