Annotation of wikisrc/tutorials/kqueue_tutorial.mdwn, revision 1.2

1.2     ! schmonz     1: **Contents**
        !             2: 
        !             3: [[!toc levels=3]]
        !             4: 
        !             5: #   Introduction
        !             6: 
        !             7: The purpose of this document is to introduce the programmer to the methodology of kqueue, rather than providing a full and exhaustive documentation of its capabilities. 
        !             8: 
        !             9: Kqueue provides a standard API for applications to register their interest in various events/conditions and have the notifications for these delivered in an efficient way. It was designed to be scalable, flexible, reliable and correct. 
        !            10: 
        !            11: #   kqueue API
        !            12: 
        !            13: ##   kevent data structure
        !            14: 
        !            15: The kevent structure goes like this: 
        !            16:     
        !            17:     struct kevent {
        !            18:                 uintptr_t ident;        /* identifier for this event */
        !            19:                 short     filter;       /* filter for event */
        !            20:                 u_short   flags;        /* action flags for kqueue */
        !            21:                 u_int     fflags;       /* filter flag value */
        !            22:                 intptr_t  data;         /* filter data value */
        !            23:                 void      *udata;       /* opaque user data identifier */
        !            24:     };
        !            25:     
        !            26: 
        !            27: ###   <ident, filter> pair
        !            28: 
        !            29: A kevent is identified by an <ident, filter> pair. The `ident` might be a descriptor (file, socket, stream), a process ID or a signal number, depending on what we want to monitor. The `filter` identifies the kernel filter used to process the respective event. There are some pre-defined system filters, such as EVFILT_READ or EVFILT_WRITE, that are triggered when data exists for read or write operation is possible respectively. 
        !            30: 
        !            31: If for instance we want to be notified when there's data available for reading in a socket, we have to specify a kevent in the form `<sckfd, EVFILT_READ>`, where sckfd is the file descriptor associated with the socket. If we would like to monitor the activity of a process, we would need a `<pid, EVFILT_PROC>` tuple. Keep in mind there can be only one kevent with the same <ident, filter> in our kqueue. 
        !            32: 
        !            33: ###   flags
        !            34: 
        !            35: After having designed a kevent, we should decide whether we want to have it added to our kqueue. For this purpose we set the `flags` member to `EV_ADD`. We could also delete an existing one by setting `EV_DELETE` or just disable it with `EV_DISABLE`. 
        !            36: 
        !            37: Combinations may be made by OR'ing the desired values. For instance, `EV_ADD | EV_ENABLE | EV_ONESHOT` would translate to "Add the event, enable it and return only the first occurrence of the filter being triggered. After the user retrieves the event from the kqueue, delete it." 
        !            38: 
        !            39: Reversely, if we would like to check whether a flag is set in a kevent, we would do it by AND'ing with the respective value. For instance: 
        !            40:     
        !            41:     if (myevent.flags & EV_ERROR) {
        !            42:        /* handle errors */
        !            43:     }
        !            44:     
        !            45: 
        !            46: ###   EV_SET() macro
        !            47: 
        !            48: The EV_SET() macro is provided for ease of initializing a kevent structure. For the time being we won't elaborate on the rest of the kevent members; instead let's have a look at the case when we need to monitor a socket for any pending data for reading: 
        !            49:     
        !            50:     kevent ev;
        !            51:     
        !            52:     EV_SET(&ev, sckfd, EVFILT_READ, EV_ADD, 0, 0, 0);
        !            53:     
        !            54: 
        !            55: [![][18]][19]
        !            56: 
        !            57:    [18]: /images/Kevent.png
        !            58:    [19]: /images/Kevent.png (Kevent.png)
        !            59: 
        !            60: If we liked to monitor a set of N sockets we would write something like this: 
        !            61:     
        !            62:     kevent ev[N];
        !            63:     int i;
        !            64:     
        !            65:     for (i = 0; i < N; i++)
        !            66:        EV_SET(&ev[i], sckfd[i], EVFILT_READ, EV_ADD, 0, 0, 0);
        !            67:     
        !            68: 
        !            69: [![][20]][21]
        !            70: 
        !            71:    [20]: /images/Kevent2.png
        !            72:    [21]: /images/Kevent2.png (Kevent2.png)
        !            73: 
        !            74: ##   kqueue(2)
        !            75: 
        !            76: The kqueue holds all the events we are interested in. Therefore, to begin with, we must create a new kqueue. We do so with the following code: 
        !            77:     
        !            78:     int kq;
        !            79:     
        !            80:     if ((kq = kqueue()) == -1) {
        !            81:        perror("kqueue");
        !            82:        exit(EXIT_FAILURE);
        !            83:     }
        !            84:     
        !            85: 
        !            86: ##   kevent(2)
        !            87: 
        !            88: At this point the kqueue is empty. In order to populate it with a set of events, we use the kevent(2) function. This system call takes the array of events we constructed before and does not return until at least one event is received (or when an associated timeout is exhausted). The function returns the number of changes received and stores information about them in another array of struct kevent elements. 
        !            89:     
        !            90:     kevent chlist[N];   /* events we want to monitor */
        !            91:     kevent evlist[N];   /* events that were triggered */
        !            92:     int nev, i;
        !            93:     
        !            94:     /* populate chlist with the events we are interested in */
        !            95:     /* ... */
        !            96:      
        !            97:     /* loop forever */
        !            98:     for (;;) {
        !            99:        nev = kevent(kq, chlist, N, 
        !           100:                         evlist, N,
        !           101:                         NULL);   /* block indefinitely */
        !           102:     
        !           103:        if (nev == -1) {
        !           104:           perror("kevent()");
        !           105:           exit(EXIT_FAILURE);
        !           106:        }
        !           107:        else if (nev > 0) {
        !           108:           for (i = 0; i < nev; i++) {
        !           109:              /* handle events */
        !           110:           }
        !           111:        }
        !           112:     }
        !           113:     
        !           114: 
        !           115: ###   timeout
        !           116: 
        !           117: Sometimes it is useful to set an upper time limit for kevent() to block. That way, it will return, no matter if none of the events was triggered. For this purpose we need the `timespec` structure, which is defined in `sys/time.h`: 
        !           118:     
        !           119:     struct timespec {
        !           120:                 time_t tv_sec;        /* seconds */
        !           121:                 long   tv_nsec;       /* and nanoseconds */
        !           122:     };
        !           123:     
        !           124: 
        !           125: The above code would turn into the following: 
        !           126:     
        !           127:     kevent chlist[N];   /* events we want to monitor */
        !           128:     kevent evlist[N];   /* events that were triggered */
        !           129:     struct timespec tmout = { 5,     /* block for 5 seconds at most */ 
        !           130:                               0 };   /* nanoseconds */
        !           131:     int nev, i;
        !           132:     
        !           133:     /* populate chlist with the events we are interested in */
        !           134:     /* ... */
        !           135:      
        !           136:     /* loop forever */
        !           137:     for (;;) {
        !           138:        nev = kevent(kq, chlist, N, 
        !           139:                         evlist, N,
        !           140:                         &tmout);   /* set upper time limit to block */
        !           141:     
        !           142:        if (nev == -1) {
        !           143:           perror("kevent()");
        !           144:           exit(EXIT_FAILURE);
        !           145:        }
        !           146:        else if (nev == 0) {
        !           147:           /* handle timeout */
        !           148:        }
        !           149:        else if (nev > 0) {
        !           150:           for (i = 0; i < nev; i++) {
        !           151:              /* handle events */
        !           152:           }
        !           153:        }
        !           154:     }
        !           155:     
        !           156: 
        !           157: Note that if one uses a non-NULL zero timespec structure, the kevent() will return instantaneously, bringing down the performance to the levels of a plain poll method. 
        !           158: 
        !           159: ##   Summary
        !           160: 
        !           161: To summarize, the kqueue framework works like this: 
        !           162: 
        !           163: [![][22]][23]
        !           164: 
        !           165:    [22]: /images/Summary.png
        !           166:    [23]: /images/Summary.png (Summary.png)
        !           167: 
        !           168: #   Examples
        !           169: 
        !           170: ##   A timer example
        !           171: 
        !           172: The following code will setup a timer that will trigger a kevent every 5 seconds. Once it does, the process will fork and the child will execute the date(1) command. 
        !           173:     
        !           174:     #include <sys/event.h>
        !           175:     #include <sys/time.h>
        !           176:     #include <stdio.h>
        !           177:     #include <stdlib.h>
        !           178:     #include <string.h>   /* for strerror() */
        !           179:     #include <unistd.h>
        !           180:     
        !           181:     /* function prototypes */
        !           182:     void diep(const char *s);
        !           183:     
        !           184:     int main(void)
        !           185:     {
        !           186:        struct kevent change;    /* event we want to monitor */
        !           187:        struct kevent event;     /* event that was triggered */
        !           188:        pid_t pid;
        !           189:        int kq, nev;
        !           190:     
        !           191:        /* create a new kernel event queue */
        !           192:        if ((kq = kqueue()) == -1)
        !           193:           diep("kqueue()");
        !           194:     
        !           195:        /* initalise kevent structure */
        !           196:        EV_SET(&change, 1, EVFILT_TIMER, EV_ADD | EV_ENABLE, 0, 5000, 0);
        !           197:     
        !           198:        /* loop forever */
        !           199:        for (;;) {
        !           200:           nev = kevent(kq, &change, 1, &event, 1, NULL);
        !           201:     
        !           202:           if (nev < 0)
        !           203:              diep("kevent()");
        !           204:     
        !           205:           else if (nev > 0) {
        !           206:              if (event.flags & EV_ERROR) {   /* report any error */
        !           207:                 fprintf(stderr, "EV_ERROR: %s\n", strerror(event.data));
        !           208:                 exit(EXIT_FAILURE);
        !           209:              }
        !           210:     
        !           211:              if ((pid = fork()) < 0)         /* fork error */
        !           212:                 diep("fork()");
        !           213:     
        !           214:              else if (pid == 0)              /* child */
        !           215:                 if (execlp("date", "date", (char *)0) < 0)
        !           216:                    diep("execlp()");
        !           217:           }
        !           218:        }
        !           219:     
        !           220:        close(kq);
        !           221:        return EXIT_SUCCESS;
        !           222:     }
        !           223:     
        !           224:     void diep(const char *s)
        !           225:     {
        !           226:        perror(s);
        !           227:        exit(EXIT_FAILURE);
        !           228:     }
        !           229:     
        !           230: 
        !           231: Compile and run: 
        !           232:     
        !           233:     $ gcc -o ktimer ktimer.c -Wall -W -Wextra -ansi -pedantic
        !           234:     $ ./ktimer
        !           235:     Tue Mar 20 15:48:16 EET 2007
        !           236:     Tue Mar 20 15:48:21 EET 2007
        !           237:     Tue Mar 20 15:48:26 EET 2007
        !           238:     Tue Mar 20 15:48:31 EET 2007
        !           239:     ^C
        !           240:     
        !           241: 
        !           242: ##   A raw tcp client
        !           243: 
        !           244: We will implement a raw tcp client using the kqueue framework. Whenever the host sends data to the socket, we will print them in the standard output stream. Similarly, when the user types something in the standard input stream, we will send it to the host through the socket. Basically, we need to monitor the following: 
        !           245: 
        !           246:   1. any incoming host data in the socket 
        !           247:   2. any user data in the standard input stream 
        !           248: 
        !           249: [![][24]][25]
        !           250:     
        !           251:    [24]: /images/Tcpclient.png
        !           252:    [25]: /images/Tcpclient.png (Tcpclient.png)
        !           253: 
        !           254: #include <netinet/in.h>
        !           255:     #include <sys/event.h>
        !           256:     #include <sys/socket.h>
        !           257:     #include <sys/time.h>
        !           258:     #include <netdb.h>
        !           259:     #include <stdio.h>
        !           260:     #include <stdlib.h>
        !           261:     #include <string.h>
        !           262:     #include <unistd.h>
        !           263:     
        !           264:     #define BUFSIZE 1024
        !           265:     
        !           266:     /* function prototypes */
        !           267:     void diep(const char *s);
        !           268:     int tcpopen(const char *host, int port);
        !           269:     void sendbuftosck(int sckfd, const char *buf, int len);
        !           270:     
        !           271:     int main(int argc, char *argv[])
        !           272:     {
        !           273:        struct kevent chlist[2];   /* events we want to monitor */
        !           274:        struct kevent evlist[2];   /* events that were triggered */
        !           275:        char buf[BUFSIZE];
        !           276:        int sckfd, kq, nev, i;
        !           277:     
        !           278:        /* check argument count */
        !           279:        if (argc != 3) {
        !           280:           fprintf(stderr, "usage: %s host port\n", argv[0]);
        !           281:           exit(EXIT_FAILURE);
        !           282:        }
        !           283:     
        !           284:        /* open a connection to a host:port pair */
        !           285:        sckfd = tcpopen(argv[1], atoi(argv[2]));
        !           286:     
        !           287:        /* create a new kernel event queue */
        !           288:        if ((kq = kqueue()) == -1)
        !           289:           diep("kqueue()");
        !           290:     
        !           291:        /* initialise kevent structures */
        !           292:        EV_SET(&chlist[0], sckfd, EVFILT_READ, EV_ADD | EV_ENABLE, 0, 0, 0);
        !           293:        EV_SET(&chlist[1], fileno(stdin), EVFILT_READ, EV_ADD | EV_ENABLE, 0, 0, 0);
        !           294:     
        !           295:        /* loop forever */
        !           296:        for (;;) {
        !           297:           nev = kevent(kq, chlist, 2, evlist, 2, NULL);
        !           298:     
        !           299:           if (nev < 0)
        !           300:              diep("kevent()");
        !           301:     
        !           302:            else if (nev > 0) {
        !           303:              if (evlist[0].flags & EV_EOF)                       /* read direction of socket has shutdown */
        !           304:                 exit(EXIT_FAILURE);
        !           305:     
        !           306:              for (i = 0; i < nev; i++) {
        !           307:                 if (evlist[i].flags & EV_ERROR) {                /* report errors */
        !           308:                    fprintf(stderr, "EV_ERROR: %s\n", strerror(evlist[i].data));
        !           309:                    exit(EXIT_FAILURE);
        !           310:                 }
        !           311:     
        !           312:                 if (evlist[i].ident == sckfd) {                  /* we have data from the host */
        !           313:                    memset(buf, 0, BUFSIZE);
        !           314:                    if (read(sckfd, buf, BUFSIZE) < 0)
        !           315:                       diep("read()");
        !           316:                    fputs(buf, stdout);
        !           317:                 }
        !           318:     
        !           319:                 else if (evlist[i].ident == fileno(stdin)) {     /* we have data from stdin */
        !           320:                    memset(buf, 0, BUFSIZE);
        !           321:                    fgets(buf, BUFSIZE, stdin);
        !           322:                    sendbuftosck(sckfd, buf, strlen(buf));
        !           323:                 }
        !           324:              }
        !           325:           }
        !           326:        }
        !           327:     
        !           328:        close(kq);
        !           329:        return EXIT_SUCCESS;
        !           330:     }
        !           331:     
        !           332:     void diep(const char *s)
        !           333:     {
        !           334:        perror(s);
        !           335:        exit(EXIT_FAILURE);
        !           336:     }
        !           337:     
        !           338:     int tcpopen(const char *host, int port)
        !           339:     {
        !           340:        struct sockaddr_in server;
        !           341:        struct hostent *hp;
        !           342:        int sckfd;
        !           343:     
        !           344:        if ((hp = gethostbyname(host)) == NULL)
        !           345:           diep("gethostbyname()");
        !           346:     
        !           347:        if ((sckfd = socket(PF_INET, SOCK_STREAM, 0)) < 0)
        !           348:           diep("socket()");
        !           349:     
        !           350:        server.sin_family = AF_INET;
        !           351:        server.sin_port = htons(port);
        !           352:        server.sin_addr = *((struct in_addr *)hp->h_addr);
        !           353:        memset(&(server.sin_zero), 0, 8);
        !           354:     
        !           355:        if (connect(sckfd, (struct sockaddr *)&server, sizeof(struct sockaddr)) < 0)
        !           356:           diep("connect()");
        !           357:     
        !           358:        return sckfd;
        !           359:     }
        !           360:     
        !           361:     void sendbuftosck(int sckfd, const char *buf, int len)
        !           362:     {
        !           363:        int bytessent, pos;
        !           364:     
        !           365:        pos = 0;
        !           366:        do {
        !           367:           if ((bytessent = send(sckfd, buf + pos, len - pos, 0)) < 0)
        !           368:              diep("send()");
        !           369:           pos += bytessent;
        !           370:        } while (bytessent > 0);
        !           371:     }
        !           372:     
        !           373: 
        !           374: Compile and run: 
        !           375:     
        !           376:     $ gcc -o kclient kclient.c -Wall -W -Wextra -ansi -pedantic
        !           377:     $ ./kclient irc.freenode.net 7000
        !           378:     NOTICE AUTH :*** Looking up your hostname...
        !           379:     NOTICE AUTH :*** Found your hostname, welcome back
        !           380:     NOTICE AUTH :*** Checking ident
        !           381:     NOTICE AUTH :*** No identd (auth) response
        !           382:     _USER guest tolmoon tolsun :Ronnie Reagan
        !           383:     NICK Wiz_
        !           384:     :herbert.freenode.net 001 Wiz :Welcome to the freenode IRC Network Wiz
        !           385:     ^C 
        !           386:     
        !           387: 
        !           388: (Whatever is in _italics_ it is what we type.) 
        !           389: 
        !           390: ##   More examples
        !           391: 
        !           392: More kqueue examples (including the aforementioned) may be found [here](http://repo.or.cz/w/eleutheria.git?a=tree;h=master;hb=master). 
        !           393: 
        !           394:    [26]: http://repo.or.cz/w/eleutheria.git?a=tree;h=master;hb=master (http://repo.or.cz/w/eleutheria.git?a=tree;h=master;hb=master)
        !           395: 
        !           396: #   Documentation
        !           397: 
        !           398:   1. [kqueue, kevent NetBSD Manual Pages](http://netbsd.gw.com/cgi-bin/man-cgi?kqueue++NetBSD-current)
        !           399:   2. [Kqueue: A generic and scalable event notification facility (pdf)](http://people.freebsd.org/~jlemon/papers/kqueue.pdf)
        !           400:   3. [kqueue slides](http://people.freebsd.org/~jlemon/kqueue_slides/)
        !           401:   4. [The Julipedia: An example of kqueue](http://julipedia.blogspot.com/2004/10/example-of-kqueue.html)
        !           402: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb