Poll Routines

Collaboration diagram for Poll Routines:

Macros
#define	SWITCH_POLLIN   0x001
#define	SWITCH_POLLPRI   0x002
#define	SWITCH_POLLOUT   0x004
#define	SWITCH_POLLERR   0x010
#define	SWITCH_POLLHUP   0x020
#define	SWITCH_POLLNVAL   0x040

Typedefs
typedef struct switch_pollfd	switch_pollfd_t
typedef struct fspr_pollset_t	switch_pollset_t

Functions
switch_status_t	switch_pollset_create (switch_pollset_t **pollset, uint32_t size, switch_memory_pool_t *pool, uint32_t flags)
switch_status_t	switch_pollset_add (switch_pollset_t *pollset, const switch_pollfd_t *descriptor)
switch_status_t	switch_pollset_remove (switch_pollset_t *pollset, const switch_pollfd_t *descriptor)
switch_status_t	switch_poll (switch_pollfd_t *aprset, int32_t numsock, int32_t *nsds, switch_interval_time_t timeout)
switch_status_t	switch_pollset_poll (switch_pollset_t *pollset, switch_interval_time_t timeout, int32_t *num, const switch_pollfd_t **descriptors)
switch_status_t	switch_socket_create_pollset (switch_pollfd_t **poll, switch_socket_t *sock, int16_t flags, switch_memory_pool_t *pool)
	Create a set of file descriptors to poll from a socket. More...
switch_interval_time_t	switch_interval_time_from_timeval (struct timeval *tvp)
switch_status_t	switch_socket_create_pollfd (switch_pollfd_t **pollfd, switch_socket_t *sock, int16_t flags, void *client_data, switch_memory_pool_t *pool)
	Create a pollfd out of a socket. More...
switch_status_t	switch_match_glob (const char *pattern, switch_array_header_t **result, switch_memory_pool_t *pool)
switch_status_t	switch_os_sock_get (switch_os_socket_t *thesock, switch_socket_t *sock)
switch_status_t	switch_os_sock_put (switch_socket_t **sock, switch_os_socket_t *thesock, switch_memory_pool_t *pool)
switch_status_t	switch_socket_addr_get (switch_sockaddr_t **sa, switch_bool_t remote, switch_socket_t *sock)
switch_status_t	switch_file_pipe_create (switch_file_t **in, switch_file_t **out, switch_memory_pool_t *pool)
switch_status_t	switch_file_pipe_timeout_get (switch_file_t *thepipe, switch_interval_time_t *timeout)
switch_status_t	switch_file_pipe_timeout_set (switch_file_t *thepipe, switch_interval_time_t timeout)
switch_status_t	switch_thread_exit (switch_thread_t *thd, switch_status_t retval)
switch_status_t	switch_thread_join (switch_status_t *retval, switch_thread_t *thd)
char *	switch_strerror (switch_status_t statcode, char *buf, switch_size_t bufsize)

Detailed Description

Macro Definition Documentation

SWITCH_POLLERR

#define SWITCH_POLLERR   0x010

Pending error

Definition at line 1339 of file switch_apr.h.

Referenced by enable_local_rtcp_socket(), and switch_rtp_set_local_address().

SWITCH_POLLHUP

#define SWITCH_POLLHUP   0x020

Hangup occurred

Definition at line 1340 of file switch_apr.h.

SWITCH_POLLIN

#define SWITCH_POLLIN   0x001

Poll optionsCan read without blocking

Definition at line 1336 of file switch_apr.h.

Referenced by enable_local_rtcp_socket(), and switch_rtp_set_local_address().

SWITCH_POLLNVAL

#define SWITCH_POLLNVAL   0x040

Descriptior invalid

Definition at line 1341 of file switch_apr.h.

SWITCH_POLLOUT

#define SWITCH_POLLOUT   0x004

Can write without blocking

Definition at line 1338 of file switch_apr.h.

SWITCH_POLLPRI

#define SWITCH_POLLPRI   0x002

Priority data available

Definition at line 1337 of file switch_apr.h.

Typedef Documentation

switch_pollfd_t

typedef struct switch_pollfd switch_pollfd_t

Poll descriptor set.

Definition at line 1328 of file switch_apr.h.

switch_pollset_t

typedef struct fspr_pollset_t switch_pollset_t

Opaque structure used for pollset API

Definition at line 1331 of file switch_apr.h.

Function Documentation

switch_file_pipe_create()

switch_status_t switch_file_pipe_create	(	switch_file_t **	in,
		switch_file_t **	out,
		switch_memory_pool_t *	pool
	)

Create an anonymous pipe.

Parameters

in	The file descriptor to use as input to the pipe.
out	The file descriptor to use as output from the pipe.
pool	The pool to operate on.

Definition at line 1337 of file switch_apr.c.

{
        return fspr_file_pipe_create((fspr_file_t **) in, (fspr_file_t **) out, pool);
}

switch_file_pipe_timeout_get()

switch_status_t switch_file_pipe_timeout_get	(	switch_file_t *	thepipe,
		switch_interval_time_t *	timeout
	)

Get the timeout value for a pipe or manipulate the blocking state.

Parameters

thepipe	The pipe we are getting a timeout for.
timeout	The current timeout value in microseconds.

Definition at line 1347 of file switch_apr.c.

{
        return fspr_file_pipe_timeout_get((fspr_file_t *) thepipe, (fspr_interval_time_t *) timeout);
}

switch_file_pipe_timeout_set()

switch_status_t switch_file_pipe_timeout_set	(	switch_file_t *	thepipe,
		switch_interval_time_t	timeout
	)

Set the timeout value for a pipe or manipulate the blocking state.

Parameters

thepipe	The pipe we are setting a timeout on.
timeout	The timeout value in microseconds. Values < 0 mean wait forever, 0 means do not wait at all.

Definition at line 1358 of file switch_apr.c.

{
        return fspr_file_pipe_timeout_set((fspr_file_t *) thepipe, (fspr_interval_time_t) timeout);
}

switch_interval_time_from_timeval()

switch_interval_time_t switch_interval_time_from_timeval

(

struct timeval *

tvp

)

Definition at line 705 of file switch_apr.c.

{
        return ((switch_interval_time_t)tvp->tv_sec * 1000000) + tvp->tv_usec / 1000;
}

switch_match_glob()

switch_status_t switch_match_glob	(	const char *	pattern,
		switch_array_header_t **	result,
		switch_memory_pool_t *	pool
	)

Definition at line 1326 of file switch_apr.c.

{
        return fspr_match_glob(pattern, (fspr_array_header_t **) result, pool);
}

switch_os_sock_get()

switch_status_t switch_os_sock_get	(	switch_os_socket_t *	thesock,
		switch_socket_t *	sock
	)

Definition at line 712 of file switch_apr.c.

Referenced by msrp_worker().

{
        return fspr_os_sock_get(thesock, sock);
}

switch_os_sock_put()

switch_status_t switch_os_sock_put	(	switch_socket_t **	sock,
		switch_os_socket_t *	thesock,
		switch_memory_pool_t *	pool
	)

Definition at line 717 of file switch_apr.c.

{
        return fspr_os_sock_put(sock, thesock, pool);
}

switch_poll()

switch_status_t switch_poll	(	switch_pollfd_t *	aprset,
		int32_t	numsock,
		int32_t *	nsds,
		switch_interval_time_t	timeout
	)

Poll the sockets in the poll structure

Parameters

aprset	The poll structure we will be using.
numsock	The number of sockets we are polling
nsds	The number of sockets signalled.
timeout	The amount of time in microseconds to wait. This is a maximum, not a minimum. If a socket is signalled, we will wake up before this time. A negative number means wait until a socket is signalled.

Remarks

The number of sockets signalled is returned in the third argument. This is a blocking call, and it will not return until either a socket has been signalled, or the timeout has expired.

Definition at line 1100 of file switch_apr.c.

References SWITCH_STATUS_FALSE, SWITCH_STATUS_GENERR, and SWITCH_STATUS_TIMEOUT.

Referenced by read_rtp_packet(), rtp_common_read(), and switch_socket_waitfor().

{
        fspr_status_t st = SWITCH_STATUS_FALSE;

        if (aprset) {
                st = fspr_poll((fspr_pollfd_t *) aprset, numsock, nsds, timeout);

                if (numsock == 1 && ((aprset[0].rtnevents & APR_POLLERR) || (aprset[0].rtnevents & APR_POLLHUP) || (aprset[0].rtnevents & APR_POLLNVAL))) {
                        st = SWITCH_STATUS_GENERR;
                } else if (st == APR_TIMEUP) {
                        st = SWITCH_STATUS_TIMEOUT;
                }
        }

        return st;
}

switch_pollset_add()

switch_status_t switch_pollset_add	(	switch_pollset_t *	pollset,
		const switch_pollfd_t *	descriptor
	)

Add a socket or file descriptor to a pollset

Parameters

pollset	The pollset to which to add the descriptor
descriptor	The descriptor to add

Remarks

If you set client_data in the descriptor, that value will be returned in the client_data field whenever this descriptor is signalled in fspr_pollset_poll().

If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to fspr_pollset_poll() for this same pollset that is being modified via fspr_pollset_add() in thread T2, the currently executing fspr_pollset_poll() call in T1 will either: (1) automatically include the newly added descriptor in the set of descriptors it is watching or (2) return immediately with APR_EINTR. Option (1) is recommended, but option (2) is allowed for implementations where option (1) is impossible or impractical.

Definition at line 1046 of file switch_apr.c.

References SWITCH_STATUS_FALSE.

Referenced by switch_socket_create_pollset().

{
        if (!pollset || !descriptor) {
                return SWITCH_STATUS_FALSE;
        }

        return fspr_pollset_add((fspr_pollset_t *) pollset, (const fspr_pollfd_t *) descriptor);
}

switch_pollset_create()

switch_status_t switch_pollset_create	(	switch_pollset_t **	pollset,
		uint32_t	size,
		switch_memory_pool_t *	pool,
		uint32_t	flags
	)

Setup a pollset object

Parameters

pollset	The pointer in which to return the newly created object
size	The maximum number of descriptors that this pollset can hold
pool	The pool from which to allocate the pollset
flags	Optional flags to modify the operation of the pollset.

Remarks

If flags equals APR_POLLSET_THREADSAFE, then a pollset is created on which it is safe to make concurrent calls to fspr_pollset_add(), fspr_pollset_remove() and fspr_pollset_poll() from separate threads. This feature is only supported on some platforms; the fspr_pollset_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.

Definition at line 1041 of file switch_apr.c.

Referenced by switch_socket_create_pollset().

{
        return fspr_pollset_create(pollset, size, pool, flags);
}

switch_pollset_poll()

switch_status_t switch_pollset_poll	(	switch_pollset_t *	pollset,
		switch_interval_time_t	timeout,
		int32_t *	num,
		const switch_pollfd_t **	descriptors
	)

Block for activity on the descriptor(s) in a pollset

Parameters

pollset	The pollset to use
timeout	Timeout in microseconds
num	Number of signalled descriptors (output parameter)
descriptors	Array of signalled descriptors (output parameter)

Definition at line 1085 of file switch_apr.c.

References SWITCH_STATUS_FALSE, and SWITCH_STATUS_TIMEOUT.

{
        fspr_status_t st = SWITCH_STATUS_FALSE;

        if (pollset) {
                st = fspr_pollset_poll((fspr_pollset_t *) pollset, timeout, num, (const fspr_pollfd_t **) descriptors);

                if (st == APR_TIMEUP) {
                        st = SWITCH_STATUS_TIMEOUT;
                }
        }

        return st;
}

switch_pollset_remove()

switch_status_t switch_pollset_remove	(	switch_pollset_t *	pollset,
		const switch_pollfd_t *	descriptor
	)

Remove a descriptor from a pollset

Parameters

pollset	The pollset from which to remove the descriptor
descriptor	The descriptor to remove

Remarks

If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to fspr_pollset_poll() for this same pollset that is being modified via fspr_pollset_remove() in thread T2, the currently executing fspr_pollset_poll() call in T1 will either: (1) automatically exclude the newly added descriptor in the set of descriptors it is watching or (2) return immediately with APR_EINTR. Option (1) is recommended, but option (2) is allowed for implementations where option (1) is impossible or impractical.

Definition at line 1055 of file switch_apr.c.

References SWITCH_STATUS_FALSE.

{
        if (!pollset || !descriptor) {
                return SWITCH_STATUS_FALSE;
        }

        return fspr_pollset_remove((fspr_pollset_t *) pollset, (const fspr_pollfd_t *) descriptor);
}

switch_socket_addr_get()

switch_status_t switch_socket_addr_get	(	switch_sockaddr_t **	sa,
		switch_bool_t	remote,
		switch_socket_t *	sock
	)

Definition at line 722 of file switch_apr.c.

Referenced by msrp_listener().

{
        return fspr_socket_addr_get(sa, (fspr_interface_e) remote, sock);
}

switch_socket_create_pollfd()

switch_status_t switch_socket_create_pollfd	(	switch_pollfd_t **	pollfd,
		switch_socket_t *	sock,
		int16_t	flags,
		void *	client_data,
		switch_memory_pool_t *	pool
	)

Create a pollfd out of a socket.

Parameters

pollfd	the pollfd to create
sock	the socket to add
flags	the flags to modify the behaviour
client_data	custom user data
pool	the memory pool to use

Returns

SWITCH_STATUS_SUCCESS when successful

Definition at line 1064 of file switch_apr.c.

References memset(), SWITCH_STATUS_FALSE, SWITCH_STATUS_MEMERR, and SWITCH_STATUS_SUCCESS.

Referenced by switch_socket_create_pollset().

{
        if (!pollfd || !sock) {
                return SWITCH_STATUS_FALSE;
        }

        if ((*pollfd = (switch_pollfd_t*)fspr_palloc(pool, sizeof(switch_pollfd_t))) == 0) {
                return SWITCH_STATUS_MEMERR;
        }

        memset(*pollfd, 0, sizeof(switch_pollfd_t));

        (*pollfd)->desc_type = (switch_pollset_type_t) APR_POLL_SOCKET;
        (*pollfd)->reqevents = flags;
        (*pollfd)->desc.s = sock;
        (*pollfd)->client_data = client_data;

        return SWITCH_STATUS_SUCCESS;
}

switch_socket_create_pollset()

switch_status_t switch_socket_create_pollset	(	switch_pollfd_t **	poll,
		switch_socket_t *	sock,
		int16_t	flags,
		switch_memory_pool_t *	pool
	)

Create a set of file descriptors to poll from a socket.

Parameters

poll	the polfd to create
sock	the socket to add
flags	the flags to modify the behaviour
pool	the memory pool to use

Returns

SWITCH_STATUS_SUCCESS when successful

Definition at line 1117 of file switch_apr.c.

References switch_pollset_add(), switch_pollset_create(), switch_socket_create_pollfd(), SWITCH_STATUS_GENERR, and SWITCH_STATUS_SUCCESS.

Referenced by enable_local_rtcp_socket(), and switch_rtp_set_local_address().

{
        switch_pollset_t *pollset;

        if (switch_pollset_create(&pollset, 1, pool, 0) != SWITCH_STATUS_SUCCESS) {
                return SWITCH_STATUS_GENERR;
        }

        if (switch_socket_create_pollfd(poll, sock, flags, sock, pool) != SWITCH_STATUS_SUCCESS) {
                return SWITCH_STATUS_GENERR;
        }

        if (switch_pollset_add(pollset, *poll) != SWITCH_STATUS_SUCCESS) {
                return SWITCH_STATUS_GENERR;
        }

        return SWITCH_STATUS_SUCCESS;
}

switch_strerror()

char* switch_strerror	(	switch_status_t	statcode,
		char *	buf,
		switch_size_t	bufsize
	)

Return a human readable string describing the specified error.

Parameters

statcode	The error code the get a string for.
buf	A buffer to hold the error string. Size of the buffer to hold the string.

Definition at line 1440 of file switch_apr.c.

Referenced by msrp_socket_recv(), and msrp_worker().

{
        return fspr_strerror(statcode, buf, bufsize);
}

switch_thread_exit()

switch_status_t switch_thread_exit	(	switch_thread_t *	thd,
		switch_status_t	retval
	)

stop the current thread

Parameters

thd	The thread to stop
retval	The return value to pass back to any thread that cares

Definition at line 1369 of file switch_apr.c.

Referenced by switch_loadable_module_exec().

{
        return fspr_thread_exit((fspr_thread_t *) thd, retval);
}

switch_thread_join()

switch_status_t switch_thread_join	(	switch_status_t *	retval,
		switch_thread_t *	thd
	)

block until the desired thread stops executing.

Parameters

retval	The return value from the dead thread.
thd	The thread to join

Definition at line 1379 of file switch_apr.c.

References SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, switch_log_printf(), and SWITCH_STATUS_FALSE.

Referenced by do_shutdown(), record_callback(), speech_callback(), switch_core_media_bug_destroy(), switch_core_media_deactivate_rtp(), switch_core_media_set_video_file(), switch_core_memory_stop(), switch_core_sqldb_stop(), switch_event_shutdown(), switch_ivr_deactivate_unicast(), switch_ivr_enterprise_originate(), switch_ivr_originate(), switch_loadable_module_shutdown(), switch_log_shutdown(), switch_msrp_destroy(), switch_nat_thread_stop(), switch_scheduler_task_thread_stop(), and switch_sql_queue_manager_stop().

{
        if ( !thd ) {
                switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "ERROR: Attempting to join thread that does not exist\n");
                return SWITCH_STATUS_FALSE;
        }

        return fspr_thread_join((fspr_status_t *) retval, (fspr_thread_t *) thd);
}