Poll Routines
[Brought To You By APR]

Collaboration diagram for Poll Routines:

Defines
#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 switch_pollfd	switch_pollfd_t
typedef apr_pollset_t	switch_pollset_t
Functions
switch_status_t	switch_pollset_create (switch_pollset_t **pollset, uint32_t size, switch_memory_pool_t *p, 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.
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.
switch_status_t	switch_match_glob (const char *pattern, switch_array_header_t **result, switch_memory_pool_t *p)
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 *p)
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)

---

Define Documentation

#define SWITCH_POLLERR   0x010

Pending error

Definition at line 1346 of file switch_apr.h.

Referenced by enable_local_rtcp_socket(), and switch_rtp_set_local_address().

#define SWITCH_POLLHUP   0x020

Hangup occurred

Definition at line 1347 of file switch_apr.h.

#define SWITCH_POLLIN   0x001

Poll options Can read without blocking

Definition at line 1343 of file switch_apr.h.

Referenced by enable_local_rtcp_socket(), and switch_rtp_set_local_address().

#define SWITCH_POLLNVAL   0x040

Descriptior invalid

Definition at line 1348 of file switch_apr.h.

#define SWITCH_POLLOUT   0x004

Can write without blocking

Definition at line 1345 of file switch_apr.h.

#define SWITCH_POLLPRI   0x002

Priority data available

Definition at line 1344 of file switch_apr.h.

---

Typedef Documentation

typedef struct switch_pollfd switch_pollfd_t

Poll descriptor set.

Definition at line 1335 of file switch_apr.h.

typedef struct apr_pollset_t switch_pollset_t

Opaque structure used for pollset API

Definition at line 1338 of file switch_apr.h.

---

Function Documentation

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

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 1128 of file switch_apr.c.

{
        return apr_file_pipe_create((apr_file_t **) in, (apr_file_t **) out, p);
}

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 1138 of file switch_apr.c.

{
        return apr_file_pipe_timeout_get((apr_file_t *) thepipe, (apr_interval_time_t *) timeout);
}

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 1149 of file switch_apr.c.

{
        return apr_file_pipe_timeout_set((apr_file_t *) thepipe, (apr_interval_time_t) timeout);
}

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

Definition at line 1117 of file switch_apr.c.

{
        return apr_match_glob(pattern, (apr_array_header_t **) result, p);
}

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 936 of file switch_apr.c.

References SWITCH_STATUS_FALSE, and SWITCH_STATUS_TIMEOUT.

Referenced by rtp_common_read(), and switch_socket_waitfor().

{
        apr_status_t st = SWITCH_STATUS_FALSE;

        if (aprset) {
                st = apr_poll((apr_pollfd_t *) aprset, numsock, nsds, timeout);

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

        return st;
}

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 apr_pollset_poll().

If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to apr_pollset_poll() for this same pollset that is being modified via apr_pollset_add() in thread T2, the currently executing apr_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 882 of file switch_apr.c.

References SWITCH_STATUS_FALSE.

Referenced by switch_socket_create_pollset().

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

        return apr_pollset_add((apr_pollset_t *) pollset, (const apr_pollfd_t *) descriptor);
}

switch_status_t switch_pollset_create	(	switch_pollset_t **	pollset,
		uint32_t	size,
		switch_memory_pool_t *	p,
		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
	p	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 apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from separate threads. This feature is only supported on some platforms; the apr_pollset_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.

Definition at line 877 of file switch_apr.c.

Referenced by switch_socket_create_pollset().

{
        return apr_pollset_create(pollset, size, p, flags);
}

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 921 of file switch_apr.c.

References SWITCH_STATUS_FALSE, and SWITCH_STATUS_TIMEOUT.

{
        apr_status_t st = SWITCH_STATUS_FALSE;
        
        if (pollset) {
                st = apr_pollset_poll((apr_pollset_t *) pollset, timeout, num, (const apr_pollfd_t **) descriptors);
                
                if (st == APR_TIMEUP) {
                        st = SWITCH_STATUS_TIMEOUT;
                }
        }
        
        return st;
}

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 apr_pollset_poll() for this same pollset that is being modified via apr_pollset_remove() in thread T2, the currently executing apr_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 891 of file switch_apr.c.

References SWITCH_STATUS_FALSE.

{
        if (!pollset || !descriptor) {
                return SWITCH_STATUS_FALSE;
        }       
        
        return apr_pollset_remove((apr_pollset_t *) pollset, (const apr_pollfd_t *) descriptor);
}

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

Definition at line 668 of file switch_apr.c.

{
        return apr_socket_addr_get(sa, (apr_interface_e) remote, sock);
}

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:

	poll	the polfd 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 900 of file switch_apr.c.

References 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*)apr_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_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 951 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;
}

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 1226 of file switch_apr.c.

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

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 1160 of file switch_apr.c.

Referenced by switch_loadable_module_exec().

{
        return apr_thread_exit((apr_thread_t *) thd, retval);
}

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 1170 of file switch_apr.c.

Referenced by audio_bridge_thread(), do_shutdown(), switch_core_memory_stop(), switch_core_sqldb_stop(), switch_event_shutdown(), switch_ivr_enterprise_originate(), switch_loadable_module_shutdown(), switch_log_shutdown(), switch_nat_thread_stop(), and switch_scheduler_task_thread_stop().

{
        return apr_thread_join((apr_status_t *) retval, (apr_thread_t *) thd);
}

---