Hi On Sat, May 17, 2014 at 12:10:36PM -0600, Ted Bullock wrote: > On Sat, May 17, 2014 at 12:08 PM, Ted Bullock <tbull...@comlore.com> wrote: > > On Sat, May 17, 2014 at 3:33 AM, Jason McIntyre <j...@kerhand.co.uk> 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 > >>> <nicholas.marri...@gmail.com> 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? >
What approach are you (Ted) going to take here? I don't fancy doing loads of relatively small commits to event(3). Would it be better to first copy the existing text in event(3) out into the set of pages you outlined earlier? And then work on each page one at a time? > > > Ok Thanks Jason, here is a revised patch with including your comments > I've copied tech@ here too btw. > > 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 .
