From 395d2df573a5b4019735cb6e52529a383458108b Mon Sep 17 00:00:00 2001 From: Joachim Nilsson Date: Thu, 17 Sep 2015 10:21:08 +0200 Subject: [PATCH] README: Add more sub-sections to API chapter, readability. Signed-off-by: Joachim Nilsson --- README.md | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index bacdbde..6c19f6c 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,11 @@ Table of Contents * [Introduction](#introduction) * [API](#api) -* [Example](#example) + * [Create an Event Context](#create-an-event-context) + * [Register Event Watcher with Event Context](#register-event-watcher-with-event-context) + * [Start Event Loop](#start-event-loop) + * [Summary](#summary) +* [Joystick Example](#joystick-example) * [Build & Install](#build--install) * [Origin & References](#origin--references) @@ -98,6 +102,8 @@ signals. With a slight caveat on signals ``` +### Create an Event Context + To monitor events the developer first creates an *event context*, this is achieved by calling `uev_init()` with a pointer to a (thread) local `uev_ctx_t` variable. @@ -110,6 +116,8 @@ is achieved by calling `uev_init()` with a pointer to a (thread) local ``` +### Register Event Watcher with Event Context + Then, for each event to be monitored, a *watcher* is registered with the event context. The watcher, an `uev_t`, is initialized with the proper file descriptor to monitor, and an event callback function, by calling @@ -123,12 +131,22 @@ the event type's `_init()` function with the `uev_ctx_t` context. uev_exit(w->ctx); } - uev_t sigterm_watcher; - - uev_signal_init(&ctx, &sigterm_watcher, cleanup_exit, NULL, SIGTERM); + int main(void) + { + uev_t sigterm_watcher; + . + . + . + uev_signal_init(&ctx, &sigterm_watcher, cleanup_exit, NULL, SIGTERM); + . + . + . + } ``` +### Start Event Loop + When all watchers are registered, call the *event loop* with `uev_run()` and the argument to the event context. The `flags` parameter can be used to integrate [libuEv][] into another event loop. With `flags` set @@ -146,7 +164,7 @@ In case of errors, stream close, or peer shutdown, libuEv handles much internally, but also lets the callback run. This is useful for stateful connections to be able to detect EOF. -Summary: +### Summary 1. Prepare an event context with `uev_init()` 2. Register event callbacks with `uev_io_init()`, `uev_signal_init()` @@ -172,8 +190,8 @@ of this, from [finit][6], implementing `run()` as a better replacement to `system()`, which sucks anyawy :) -Example -------- +Joystick Example +---------------- Here follows a very brief example to illustrate how one can use [libuEv][] to act upon joystick input. @@ -236,12 +254,13 @@ To compile the program, save the code as `joystick.c` and call GCC with directory, skips using a Makefile altogether. Alternatively, call the `Makefile` with make joystick from this directory. -More complete and relevant example uses of [libuEv] is the TFTP/FTP +More complete and relevant example uses of [libuEv][] is the TFTP/FTP server [uftpd][5], and the Linux `/sbin/init` replacement [finit][6]. Both use [libuEv][] as a GIT submodule. -Also, see the `bench.c` program (make bench from within the -library) for [reference benchmarks][7] against libevent and libev. +Also see the `bench.c` program (make bench from within the +library) for [reference benchmarks][7] against [libevent][1] and +[libev][2]. Build & Install @@ -306,7 +325,6 @@ event library used for inspiration is the very small [Picoev][9] by [Flemming Madsen]: http://www.madsensoft.dk [Dave Zarzycki, Apple]: http://www.youtube.com/watch?v=cD_s6Fjdri8 -