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? > 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 .
