CSE2410 Fall 2014 Bounce

=head1 NAME

liboi - a C library for doing evented I/O.

=head1 SYNOPSIS

    #include <oi.h>

=head1 DESCRIPTION

liboi is an object oriented library for doing evented socket and file I/O.

The API is mostly about registering callbacks to be executed on certain

events.

Because most systems do not support asynchornous file I/O, the behavior is

emulated with an internal thread pool. The thread pool is accessed with the

C<oi_async> and C<oi_task> objects. Typically one will not need to use these

directly as C<oi_file> wraps that functionality. 

=head2 CONVENTIONS

liboi's goal is to be very simple layer above the POSIX API. To that end it

avoids internal allocations as much as possible. Unless otherwise noted you

should assume all pointers passed into liboi will remain your responsibility

to maintain.  That means you should not free the data passed into liboi

until the object in question has completed.

C<oi_socket> and C<oi_file> objects must be attached to an event loop. This

is completed with the C<*_attach> and C<*_detach>  methods. When an object

is detached, other methods can be called - just the loop will not churn out

callbacks.

Both C<oi_socket> and C<oi_file> contain a number of callback pointers.

These are to be set manually after calling their initalization functions.

All classes include a C<void *data> member which is left for you to use.

=head1 ERROR HANDLING

=head1 Sockets

The C<oi_socket> structure represents a socket.

The callbacks inside C<oi_socket> are 

    void (*on_connect)   (oi_socket *);

    void (*on_read)      (oi_socket *, const void *buf, size_t count);

    void (*on_drain)     (oi_socket *);

    void (*on_error)     (oi_socket *, struct oi_error e);

    void (*on_close)     (oi_socket *);

    void (*on_timeout)   (oi_socket *);

A the memory for a socket is released when the C<on_close()> callback is

made. That is, the user may free the memory for the socket with-in the

C<on_close()> callback.

=over 4

=item void oi_socket_init (oi_socket *, float timeout);

Initialize a socket. C<timeout> is the number of seconds of inactivity that

is allowed before the socket closes. The timeout only starts once the

socket is attached to a loop and open.

A C<timeout> argument of 0.0 signals that no timeout should be used.

After calling this function, register your callbacks manually. Thus your

code will probably look like this 

    oi_socket socket;

    oi_socket_init(&socket, 60.0);

    socket.on_connect = my_on_connect;

    socket.on_read = my_on_read;

    /* etc */

=item int oi_socket_connect (oi_socket *, struct addrinfo *addrinfo);

Open a client connect to the specified address. When the connection is made

C<socket.on_connect> will be called. 

Here is an example of filling in C<addrinfo> for a local TCP connection on

port 5555:

    struct addrinfo *servinfo;

    struct addrinfo hints;

    memset(&hints, 0, sizeof hints);

    hints.ai_family = AF_UNSPEC;

    hints.ai_socktype = SOCK_STREAM;

    hints.ai_flags = AI_PASSIVE;

    r = getaddrinfo(NULL, "5555", &hints, &servinfo);

    assert(r == 0);

    oi_socket_connect(socket, servinfo);

=item void oi_socket_attach (oi_socket *, struct ev_loop *loop);

A socket must be attached to a loop in order before any callbacks will be

made. 

=item void oi_socket_detach (oi_socket *);

Detaching a socket will not close the connection.

=item void oi_socket_read_start (oi_socket *);

This will make the socket start receiving data. When data is received the

C<socket.on_read> callback is made. The maximum amount of data that can be

receive at a time is controlled by C<socket.chunksize>. 

The buffer returned by C<socket.on_read> is statically allocated exists only

for the length of the callback. That means if you need to save any of the

data coming down the line, you must copy it to a new buffer. 

Ideally you will have a parser attached to the C<on_read> callback which can

be interrupted at any time. 

C<socket.chunksize> can be changed at any time.

=item void oi_socket_read_stop (oi_socket *);

Stops receiving data. You may receive spurious C<on_read> attempts even

though the socket reading is stopped - be prepared to handle them. 

=item void oi_socket_reset_timeout (oi_socket *);

Reset the timeout to allow the socket to exist for another few seconds

(however long you specified in the initialization function).  

=item void oi_socket_write (oi_socket *socket, oi_buf *buf);

Write the I<buf> to the socket. Each socket has a queue of C<oi_buf> objects

to be written - this appends the specified buffer to the end of that queue.

You will be notified when the queue is empty with the C<socket.on_drain()>

callback. When the socket has written the buffer C<buf.release()> will be

called. The release callback does not imply that the buffer was successfully

written.

=item void oi_socket_write_simple (oi_socket *, const char *str, size_t len);

Sometimes you are just hacking around and need to quickly write a string to

the socket. This convenience function allocates an C<oi_buf> object, and

C<strdup>s  the given string. The allocated buffer will be freed by liboi

internally. 

Most production most applications will use their own memory pool and will

not need this function. 

=item void oi_socket_write_eof (oi_socket *);

This closes the write end of the socket. Further writes are not allowed

after this. 

=item void oi_socket_close (oi_socket *);

Attempts to close the socket. 

If the socket is secure, an SSL bye message will be sent. 

SSL recommends that you wait for a bye response from the peer however this

tends to be overkill for most people. By default liboi will not wait for

peer to send a matching bye message. If you require this then set

C<socket.wait_for_secure_hangup> to 1.

When the close is complete C<on_close()> is made. The C<on_close()>

callback is not made until the program returns to the event loop. This is

because C<on_close()> may free the socket memory and if C<on_close()> was

called from C<oi_socket_close()>, then the socket object might unexpectedly

be gone. To summarize: C<oi_socket_close()> does not call C<on_close()> and

the socket memory is still accessable immediately after making calling

C<oi_socket_close()>. 

=item void oi_socket_set_secure_session (oi_socket *, gnutls_session_t);

This make a socket use SSL. You must create the GnuTLS session yourself and

assign its credentials.

=back

=head1 Servers

A server simply listens on an address for new connections. The connections

come in the form of C<oi_socket> objects. The key is to give a

C<server.on_connection()> callback which returns an initialized C<oi_socket>.

The callback looks like this 

    oi_socket* (*on_connection) (oi_server *, struct sockaddr *remote_addr, socklen_t remove_addr_len);

Returning NULL from C<on_connection()> will reject the connection.

=over 4

=item void oi_server_init (oi_server *, int backlog);

Initializes a server object. C<backlog> is the argument given

internally to C<listen()>. Set the C<server.on_connection()> callback

after calling this.

=item int oi_server_listen (oi_server *, struct addrinfo *addrinfo);

Listens on the specified address. The server will not accept connections

until it is attached to a loop, however.

=item void oi_server_attach (oi_server *, struct ev_loop *loop);

Attaches a server to a loop. 

=item void oi_server_detach (oi_server *);

Detaches a server to a loop. Does not close the server.

=item void oi_server_close (oi_server *); 

Stops the server from listening. 

=back

=head1 Files

Files internally use a thread pool to operate without blocking.

The thread pool is started once a file is attached and it continues until

program termination. 

The following callbacks are used inside of the file object

    void (*on_open)  (oi_file *);

    void (*on_read)  (oi_file *, size_t count);

    void (*on_drain) (oi_file *);

    void (*on_error) (oi_file *, struct oi_error);

    void (*on_close) (oi_file *);

=over 4

=item int oi_file_init (oi_file *);

Initializes a file object.

=item void oi_file_attach (oi_file *, struct ev_loop *);

Attaches a file object to a loop. If the thread pool has not been started,

then it is started at this call. 

=item void oi_file_detach (oi_file *);

Detaches a file object from the loop.

=item int  oi_file_open_path (oi_file *, const char *path, int flags, mode_t mode);

Opens a file specified by the path. The C<flag> and C<mode> arguments are

the same as used by L<open.2>. The C<file.on_open> callback is triggered

when the file is opened. Returns 0 on success. Returns -1 if the given file

is already open.

WARNING: path argument must be valid until C<oi_file> object is closed and

the C<file.on_close()> callback is made. I.E., liboi does not strdup the path

pointer. 

=item int oi_file_open_stdin (oi_file *);

=item int oi_file_open_stdout (oi_file *);

=item int oi_file_open_stderr (oi_file *);

=item void oi_file_read_start (oi_file *, void *buffer, size_t bufsize);

=item void oi_file_read_stop (oi_file *);

=item int oi_file_write (oi_file *, oi_buf *to_write);

=item int oi_file_write_simple (oi_file *, const char *, size_t);

=item int oi_file_send (oi_file *source, oi_socket *destination, off_t offset, size_t length);

=item void oi_file_close (oi_file *);

=over 4

=back

=head1 AUTHOR

Ryan Dahl <ry@tinyclouds.org>