On Fri, Sep 21, 2018 at 06:36:54PM -0700, Geoff Hill wrote: > Hello tech, > > I noticed the event(3) manual pages don't mention the > bufferevent_setwatermark(3) function and glosses over the details of > watermarks, even though there's a few programs in userland that set both > read and write watermarks. Looks like there was an effort in 2017 > to add some documentation but it stalled. > > Here's a patch that adds the function synopsis and a brief description > of how watermarks work separately for read and write. Mostly copied from > the function declaration comments in event.h. > > ok?
Few nits below, otherwise it looks good. Anyone else willing to ok? > > Geoff Hill > > > Index: event.3 > =================================================================== > RCS file: /cvs/src/lib/libevent/event.3,v > retrieving revision 1.54 > diff -u -p -u -r1.54 event.3 > --- event.3 26 Jul 2018 12:50:04 -0000 1.54 > +++ event.3 22 Sep 2018 01:26:56 -0000 > @@ -68,6 +68,7 @@ > .Nm bufferevent_enable , > .Nm bufferevent_disable , > .Nm bufferevent_settimeout , > +.Nm bufferevent_setwatermark , > .Nm EVBUFFER_INPUT , > .Nm EVBUFFER_OUTPUT > .Nd execute a function when a specific event occurs > @@ -156,6 +157,8 @@ > .Fn "bufferevent_disable" "struct bufferevent *bufev" "short event" > .Ft void > .Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" > "int timeout_write" > +.Ft void > +.Fn "bufferevent_setwatermark" "struct bufferevent *bufev" "short events" > "size_t lowmark" "size_t highmark" > .Ft "struct evbuffer *" > .Fn "EVBUFFER_INPUT" "struct bufferevent *bufev" > .Ft "struct evbuffer *" > @@ -492,10 +495,35 @@ and > When read enabled the bufferevent will try to read from the file > descriptor and call the read callback. > The write callback is executed > -whenever the output buffer is drained below the write low watermark, > +whenever the output buffer is drained below the write > +.Fa "lowmark" , > which is > .Va 0 > by default. > +.Pp > +The > +.Fn bufferevent_setwatermark > +function can set the the low and high watermarks One `the' is enough. > +for read and write events. > +.Fa "events" > +can be > +.Va EV_READ , > +.Va EV_WRITE > +or both. > +When used with > +.Va EV_READ , > +a bufferevent does not invoke the user read callback > +unless there is at least > +.Fa "lowmark" > +data in the buffer. > +If the read buffer is beyond > +.Fa "highmark" , > +the bufferevent stops reading from the file descriptor. > +When used with > +.Va EV_WRITE, Missing space between EV_WRITE and comma. > +the user write callback is invoked whenever the buffered data > +falls below > +.Fa "lowmark" . > .Pp > The > .Fn bufferevent_write
