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? 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 +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, +the user write callback is invoked whenever the buffered data +falls below +.Fa "lowmark" . .Pp The .Fn bufferevent_write
