#include <cat/cat.h>
int catsock_add(cat_session *sess, int flags, catsock_eventfunc *eventfn);
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:
catsock_run()
to give up ownership of the session. The
event function will not be called again.
Flags can take the following values:
If CATSOCK_INIT is set, the callback will also be called directly after the thread has been created, with event set to 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.
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.
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().
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.