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' contains the current time-of-day. 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.