NAME

catsock_add - add a session to be handled

SYNOPSIS

#include <cat/cat.h>

int catsock_add(cat_session *sess, int flags, catsock_eventfunc *eventfn);

DESCRIPTION

This function adds a session to be handled by catsock_run().

flags controls how the session will be served and the meaning of parameter eventfn.

The default if flags is zero is to call cat_recv() for each descriptor that has data to be read. In this case, eventfn is not used and should be set to NULL.

The event function should match the following prototype:

  typedef int catsock_eventfunc(cat_session *sess, int event,
                                int *flagsp, void *data);

In the case where eventfn() is called, flagsp will point to an internal int containing the flags. The flags can be modified by eventfn() to change the behaviour of catsock_run() for the current session. The return value from the event handler is interpreted as follows:

CAT_OK (0)
Continue normal operation according to the flags.

CAT_CONTINUE
Proceed with the standard event handler, then continue with normal operation according to the flags.

CAT_UNMANAGE
Causes catsock_run() to give up ownership of the session. The event function will not be called again.

Any other return value is considered an error and will cause the session to be closed.

Flags can take the following values:

CATSOCK_THREAD
If supported by the implementation, a new thread will be created to handle the session. The sess pointer cannot be accessed in the current thread after the call to catsock_add(). If both CATSOCK_THREAD and CATSOCK_FORK are set, CATSOCK_THREAD has higher priority. If threads are not supported by the implementation and CATSOCK_FORK is clear, an error will be returned.

If CATSOCK_INIT is set, the callback will also be called directly after the thread has been created, with event set to CATSOCK_THREAD.

CATSOCK_FORK
If supported by the implementation, create a new process to handle the session. If this is not possible, a new thread will be created as for CATSOCK_THREAD.

If CATSOCK_INIT is set, the child process will call eventfn() with event set to CATSOCK_FORK, and the parent process will call eventfn() with event set to CATSOCK_PARENT and the data argument pointing to a pid_t containing the pid of the spawned child process.

CATSOCK_SERVER_READ
CATSOCK_CLIENT_READ
Instead of calling cat_recv() for each descriptor of a session that has data to be read, eventfn() will be called with event set to CATSOCK_CLIENT_READ or CATSOCK_SERVER_READ. If this flag is cleared by eventfn(), catsock_run() will call cat_recv() as usual for any further data.

CATSOCK_SERVER_CONNECT
CATSOCK_CLIENT_CONNECT
This can be used to test if a non-blocking connect has succeeded.

CATSOCK_LISTEN
The session to be added must have been set in a listening state by calling catnet_listen(), or an error will be returned.

When a connection is made to the port specified in the catnet_listen() call, catsock_run() will call catnet_accept() to create a new session and then call eventfn() with the new session as the data argument and CATSOCK_LISTEN as the event argument. The new session can then be added to the sessions to be handled, by calling catsock_add().

When a session has been successfully added, it becomes the property of catsock_run() and should not be accessed again except when it appears as an argument to a callback.

Whether a session starts running immediately as it is added or starts when catsock_run() is called, depends on the platform. Regardless of when a session starts, catsock_run() should eventually always be called when sessions have been added.

The function returns a negative code on error and one of 0, CATSOCK_THREAD and, CATSOCK_FORK, depending on how the session was added.

SEE ALSO

cat, catnet, cat_recv, catnet_listen, catnet_accept, catsock_run