On Sat, Sep 22, 2018 at 10:15:21AM +0200, Anton Lindqvist wrote:
> 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?
>
ok me, but please also remove the quoting from stuff like
.Fa "blah"
except for the other points you noted, reads ok.
jmc
> >
> > 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
