# Multiplexing sessions (in a one thread design)

## Name

Multiplexing sessions (in a one thread design) -- The SessionSet API allows applications to make I/O on mutilple rtp sessions without making blocking I/O, but keeping the main process synchronised.

## Synopsis

    #include <ortp.h>

                SessionSet;
    SessionSet* session_set_new                 ();
    #define     session_set_init                (ss)
    #define     session_set_set                 (ss,rtpsession)
    #define     session_set_is_set              (ss,rtpsession)
    #define     session_set_clr                 (ss,rtpsession)
    int         session_set_select              (SessionSet *recvs,
                                                 SessionSet *sends,
                                                 SessionSet *errors);
    void        session_set_destroy             (SessionSet *set);

## Description

The scheduled mode must be enabled for all rtp session that are managed through the SessionSet API. See `rtp_session_set_scheduling_mode()`.

## Details

### SessionSet

    typedef struct {
    	ortp_fd_set rtpset;
    } SessionSet;

### session_set_new ()

    SessionSet* session_set_new                 ();

Allocates and initialize a new empty session set.

Returns : | the session set.

### session_set_init()

    #define session_set_init(ss)		ORTP_FD_ZERO(&(ss)->rtpset)

Initializes a session set. It is unusefull to call this function on a session set object returned by `session_set_new()`.

`ss` : | a SessionSet statically allocated.

### session_set_set()

    #define session_set_set(ss,rtpsession)		ORTP_FD_SET((rtpsession)->mask_pos,&(ss)->rtpset)

This macro adds rtp session `_session` to set `_set`.

`ss` : | a set (SessionSet object)
`rtpsession` : | a rtp session

### session_set_is_set()

    #define session_set_is_set(ss,rtpsession)	ORTP_FD_ISSET((rtpsession)->mask_pos,&(ss)->rtpset)

This macro tests if `_session` is part of `_set`. 1 is returned if true, 0 else.

`ss` : | a set (SessionSet object)
`rtpsession` : | a rtp session

### session_set_clr()

    #define session_set_clr(ss,rtpsession)		ORTP_FD_CLR((rtpsession)->mask_pos,&(ss)->rtpset)

Removes the `_session` from the _set.

`ss` : | a set of sessions.
`rtpsession` : | a rtp session.

### session_set_select ()

    int         session_set_select              (SessionSet *recvs,
                                                 SessionSet *sends,
                                                 SessionSet *errors);

This function performs similarly as libc `select()` function, but performs on RtpSession instead of file descriptors. `session_set_select()` suspends the calling process until some events arrive on one of the three sets passed in argument. Two of the sets can be NULL. The first set `recvs` is interpreted as a set of RtpSession waiting for receive events: a new buffer (perhaps empty) is availlable on one or more sessions of the set, or the last receive operation with `rtp_session_recv_with_ts()` would have finished if it were in blocking mode. The second set is interpreted as a set of RtpSession waiting for send events, i.e. the last `rtp_session_send_with_ts()` call on a session would have finished if it were in blocking mode.

When some events arrived on some of sets, then the function returns and sets are changed to indicate the sessions where events happened. Sessions can be added to sets using `session_set_set()`, a session has to be tested to be part of a set using `session_set_is_set()`.

`recvs` : | a set of rtp sessions to be watched for read events
`sends` : | a set of rtp sessions to be watched for write events
`errors` : | a set of rtp sessions to be watched for errors
Returns : | the number of sessions on which the selected events happened.

### session_set_destroy ()

    void        session_set_destroy             (SessionSet *set);

`set` : | a SessionSet Destroys a session set.

## See Also

See the mrtprecv.c and mrtpsend.c programs included in the library that uses the SessionSet API to send or receive multiple RTP streams in one thread design.