On Sat, May 17, 2014 at 12:10:36PM -0600, Ted Bullock wrote: > On Sat, May 17, 2014 at 12:08 PM, Ted Bullock <[email protected]> wrote: > > On Sat, May 17, 2014 at 3:33 AM, Jason McIntyre <[email protected]> wrote: > >> On Sat, May 17, 2014 at 03:09:03AM -0600, Ted Bullock wrote: > >>> On Fri, May 16, 2014 at 1:10 AM, Nicholas Marriott > >>> <[email protected]> wrote: > >>> > Hi > >>> > > >>> > Yes, I think this would be nice to see. We use libevent quite a lot so > >>> > it'd be nice to have good documentation. > >>> > >>> Little patch below with some clarification on how to setup the library > >>> and what it's good for. I'm hoping gmail doesn't eat the patch :/ > >>> > >> > >> first off, i don;t want to take on the commits for this. someone else up > >> for it? > > > Ok Thanks Jason, here is a revised patch with including your comments > I've copied tech@ here too btw. >
it's ok by me. jmc > Index: event.3 > =================================================================== > RCS file: /cvs/src/lib/libevent/event.3,v > retrieving revision 1.43 > diff -u -3 -r1.43 event.3 > --- event.3 3 Apr 2014 13:30:05 -0000 1.43 > +++ event.3 17 May 2014 17:40:30 -0000 > @@ -23,7 +23,7 @@ > .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF > .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. > .\" > -.Dd $Mdocdate: April 3 2014 $ > +.Dd $Mdocdate: May 17 2014 $ > .Dt EVENT 3 > .Os > .Sh NAME > @@ -189,15 +189,45 @@ > .Fn event_asr_abort "struct event_asr *eva" > .Sh DESCRIPTION > The > -.Nm event > -API provides a mechanism to execute a function when a specific event > -on a file descriptor occurs or after a given time has passed. > +.Nm libevent > +library is an asynchronous notification mechanism intended to replace > +the main program loop for network and event-driven processes. > +The library API executes callback functions triggered by file descriptor > +activity, timeouts and signals. > +Notifications are supplied using the operating system's most efficient > +notification subsystem; on > +.Ox > +this defaults to > +.Xr kqueue 2 , > +although > +.Xr poll 2 > +and > +.Xr select 2 > +are also supported. > .Pp > -The > -.Nm event > -API needs to be initialized with > +A one-time initialization of the libevent library must be performed by > +calling either > +.Fn event_init > +or > +.Fn event_base_new , > +both of which return > +.Dv NULL > +in case of an error, or upon success return a heap allocated > +.Vt event_base > +data structure that must be passed to > +.Fn event_base_free > +to free its memory. > .Fn event_init > -before it can be used. > +is used to simplify the library API for processes that need a single > +event loop by setting a global > +.Vt event_base > +for the whole process. > +Since libevent is not directly thread-safe > +.Fn event_base_new > +is used for multi-threaded environments to create memory independent > +event loops in each thread; in these circumstances the > +.Nm event_base_* > +set of calls must be used. > .Pp > In order to process events, an application needs to call > .Fn event_dispatch .
