Scroll to navigation

ivykis(3) ivykis programmer's manual ivykis(3)

NAME

iv_examples - ivykis examples

EXAMPLE

ivykis is initialised by calling iv_init(3). This function is the first function to call when dealing with ivykis -- it has to be called before registering file descriptors or timers.

The ivykis main event loop is started by calling iv_main(3). This function generally does not return, except when iv_quit(3) is called somewhere during execution of the program.

An application asks ivykis to monitor a certain file descriptor by filling out a structure of type 'struct iv_fd' with a file descriptor number and a callback function, and calling the function iv_fd_register.

The first example program waits for data from standard input, and writes a message to standard out whenever something is received:

#include <stdio.h>
#include <stdlib.h>
#include <iv.h>
struct iv_fd fd_stdin;
static void callback(void *dummy)
{

char buf[1024];
int len;
len = read(fd_stdin.fd, buf, sizeof(buf));
if (len <= 0) {
if (len < 0) {
if (errno == EAGAIN)
return;
perror("read");
}
exit(1);
}
printf("read %d bytes of data from stdin\n", len); } int main() {
iv_init();
IV_FD_INIT(&fd_stdin);
fd_stdin.fd = 0;
fd_stdin.handler_in = callback;
iv_fd_register(&fd_stdin);
iv_main();
iv_deinit();
return 0; }

The application is responsible for memory management of 'struct iv_fd's passed to ivykis. For example, it should not free memory that contains such structures that are still registered with ivykis (i.e. haven't had iv_fd_unregister called on them).

iv_fd_register transparently sets the passed file descriptor to nonblocking mode, in anticipation of its future usage.

File descriptor callbacks are called in a level-triggered fashion. Therefore, the way of dealing with fd_stdin in the example callback function is safe. In case there arrives data between read and detecting EAGAIN, ivykis will re-call the callback function after it returns. Also, if there are more than 1024 bytes waiting in the input buffer, ivykis will re-call the callback function until all data from stdin have been drained.

EXAMPLE 2

The second example accepts connections on TCP port 6667, and waits on each of the connections for data. When data is received on any connection, a message is printed to standard out.

#include <stdio.h>
#include <stdlib.h>
#include <iv.h>
#include <netinet/in.h>
struct connection
{

struct iv_fd fd;
/* other per-connection data goes here */ }; struct listening_socket {
struct iv_fd fd;
/* other per-listening socket data goes here */ }; static void connection_handler(void *_conn) {
struct connection *conn = (struct connection *)_conn;
char buf[1024];
int len;
len = read(conn->fd.fd, buf, sizeof(buf));
if (len <= 0) {
if (len < 0 && errno == EAGAIN)
return;
iv_fd_unregister(&conn->fd);
close(conn->fd.fd);
free(conn);
return;
}
printf("got %d bytes of data from %p\n", len, conn); } static void listening_socket_handler(void *_sock) {
struct listening_socket *sock = (struct listening_socket *)_sock;
struct sockaddr_in addr;
socklen_t addrlen;
struct connection *conn;
int fd;
addrlen = sizeof(addr);
fd = accept(sock->fd.fd, (struct sockaddr *)&addr, &addrlen);
if (fd < 0) {
if (errno == EAGAIN)
return;
perror("accept");
exit(1);
}
conn = malloc(sizeof(*conn));
if (conn == NULL) {
fprintf(stderr, "listening_socket_handler: memory allocation error, dropping connection");
close(fd);
return;
}
IV_FD_INIT(&conn->fd);
conn->fd.fd = fd;
conn->fd.cookie = (void *)conn;
conn->fd.handler_in = connection_handler;
iv_fd_register(&conn->fd); } int main() {
struct listening_socket s;
struct sockaddr_in addr;
int fd;
fd = socket(AF_INET, SOCK_STREAM, 0);
if (fd < 0) {
perror("socket");
exit(1);
}
addr.sin_family = AF_INET;
addr.sin_addr.s_addr = htonl(INADDR_ANY);
addr.sin_port = htons(6667);
if (bind(fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
perror("bind");
exit(1);
}
if (listen(fd, 4) < 0) {
perror("listen");
exit(1);
}
iv_init();
IV_FD_INIT(&s.fd);
s.fd.fd = fd;
s.fd.cookie = (void *)&s;
s.fd.handler_in = listening_socket_handler;
iv_fd_register(&s.fd);
iv_main();
iv_deinit();
return 0; }

As illustrated, it is possible to pass cookies into callback functions. This is useful for conveying information on which higher-level entity (such as 'connection' or 'listening socket') generated the event for which the callback was called.

Note how it is possible to unregister and even free a 'struct iv_fd' in its own callback function. There is logic in ivykis to deal with this case.

EXAMPLE 3

This example extends the previous example by a per-connection timer that disconnects the client after too long a period of inactivity. Lines not present in example 2 or different than in example 2 are indicated by '//XXXX' in the right-hand margin.

#include <stdio.h>
#include <stdlib.h>
#include <iv.h>
#include <netinet/in.h>
#define CONNECTION_TIMEOUT      (10)
struct connection
{

struct iv_fd fd;
struct iv_timer disconnect_timeout; //XXXX
/* other per-connection data goes here */ }; struct listening_socket {
struct iv_fd fd;
/* other per-listening socket data goes here */ }; static void connection_handler(void *_conn) {
struct connection *conn = (struct connection *)_conn;
char buf[1024];
int len;
len = read(conn->fd.fd, buf, sizeof(buf));
if (len <= 0) {
if (len < 0 && errno == EAGAIN)
return;
iv_timer_unregister(&conn->disconnect_timeout); //XXXX
iv_fd_unregister(&conn->fd);
close(conn->fd.fd);
free(conn);
return;
}
printf("got %d bytes of data from %p\n", len, conn);
iv_timer_unregister(&conn->disconnect_timeout); //XXXX
iv_validate_now(); //XXXX
conn->disconnect_timeout.expires = iv_now; //XXXX
conn->disconnect_timeout.expires.tv_sec += CONNECTION_TIMEOUT;//XXXX
iv_timer_register(&conn->disconnect_timeout); //XXXX } static void disconnect_timeout_expired(void *_conn) //XXXX { //XXXX
struct connection *conn = (struct connection *)_conn; //XXXX
iv_fd_unregister(&conn->fd); //XXXX
close(conn->fd.fd); //XXXX
free(conn); //XXXX } //XXXX static void listening_socket_handler(void *_sock) {
struct listening_socket *sock = (struct listening_socket *)_sock;
struct sockaddr_in addr;
socklen_t addrlen;
struct connection *conn;
int fd;
addrlen = sizeof(addr);
fd = accept(sock->fd.fd, (struct sockaddr *)&addr, &addrlen);
if (fd < 0) {
if (errno == EAGAIN)
return;
perror("accept");
exit(1);
}
conn = malloc(sizeof(*conn));
if (conn == NULL) {
fprintf(stderr, "listening_socket_handler: memory allocation error, dropping connection");
close(fd);
return;
}
IV_FD_INIT(&conn->fd);
conn->fd.fd = fd;
conn->fd.cookie = (void *)conn;
conn->fd.handler_in = connection_handler;
iv_fd_register(&conn->fd);
IV_TIMER_INIT(&conn->disconnect_timeout); //XXXX
iv_validate_now(); //XXXX
conn->disconnect_timeout.cookie = (void *)conn; //XXXX
conn->disconnect_timeout.handler = disconnect_timeout_expired;//XXXX
conn->disconnect_timeout.expires = iv_now; //XXXX
conn->disconnect_timeout.expires.tv_sec += CONNECTION_TIMEOUT;//XXXX
iv_timer_register(&conn->disconnect_timeout); //XXXX } int main() {
struct listening_socket s;
struct sockaddr_in addr;
int fd;
fd = socket(AF_INET, SOCK_STREAM, 0);
if (fd < 0) {
perror("socket");
exit(1);
}
addr.sin_family = AF_INET;
addr.sin_addr.s_addr = htonl(INADDR_ANY);
addr.sin_port = htons(6667);
if (bind(fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
perror("bind");
exit(1);
}
if (listen(fd, 4) < 0) {
perror("listen");
exit(1);
}
iv_init();
IV_FD_INIT(&s.fd);
s.fd.fd = fd;
s.fd.cookie = (void *)&s;
s.fd.handler_in = listening_socket_handler;
iv_fd_register(&s.fd);
iv_main();
iv_deinit();
return 0; }

The global variable 'iv_now' represents a monotonic timer. However, it is updated lazily, and its contents might be stale at any given time. Before using it, iv_validate_now(3) must be called.

EXAMPLE 4

The fourth example demonstrates how to use a custom fatal error handler that does not write the message to syslog.

#include <stdio.h>
#include <iv.h>
static void fatal_error(const char *msg)
{

fprintf(stderr, "ivykis: FATAL ERROR: %s\n", msg); } int main() {
iv_init();
iv_set_fatal_msg_handler(fatal_error);
iv_fatal("Programmatically triggered fatal error %d.", 42);
printf("This code is never reached.\n");
iv_deinit();
return 0; }

This program will abort immediately, with the error message printed to the standard error stream.

SEE ALSO

ivykis(3), iv_fatal(3), iv_fd(3), iv_timer(3), iv_task(3), iv_init(3), iv_time(3)

2003-03-29 ivykis