pa_unix_util.h File Reference

#include "pa_util.h"
#include "pa_pthread_util.h"
#include "pa_cpuload.h"
#include <assert.h>
#include <pthread.h>
#include <signal.h>

Go to the source code of this file.

Data Structures
struct	PaUtilThreading
struct	PaUnixMutex
struct	PaUnixThread

Macros
#define	PA_MIN(x, y)
#define	PA_MAX(x, y)
#define	UNLIKELY(expr)
#define	PA_UNLESS_ON_ERROR(expr, code, _on_error)
#define	PA_UNLESS(expr, code)
#define	PA_UNLESS_NO_GOTO(expr, code)
#define	PA_ENSURE_ON_ERROR(expr, _on_error)
#define	PA_ENSURE(expr)
#define	PA_ENSURE_NO_GOTO(expr)
#define	PA_ASSERT_CALL(expr, success)
#define	PA_ENSURE_SYSTEM(expr, success)
#define	PaUnixThreading_EXIT(result)

Functions
PaError	PaUtil_InitializeThreading (PaUtilThreading *threading)
void	PaUtil_TerminateThreading (PaUtilThreading *threading)
PaError	PaUtil_StartThreading (PaUtilThreading *threading, void *(*threadRoutine)(void *), void *data)
PaError	PaUtil_CancelThreading (PaUtilThreading *threading, int wait, PaError *exitResult)
PaError	PaUnixMutex_Initialize (PaUnixMutex *self)
PaError	PaUnixMutex_Terminate (PaUnixMutex *self)
PaError	PaUnixMutex_Lock (PaUnixMutex *self)
PaError	PaUnixMutex_Unlock (PaUnixMutex *self)
PaError	PaUnixThreading_Initialize (void)
PaError	PaUnixThread_New (PaUnixThread *self, void *(*threadFunc)(void *), void *threadArg, PaTime waitForChild, int rtSched)
PaError	PaUnixThread_Terminate (PaUnixThread *self, int wait, PaError *exitResult)
PaError	PaUnixThread_PrepareNotify (PaUnixThread *self)
PaError	PaUnixThread_NotifyParent (PaUnixThread *self)
int	PaUnixThread_StopRequested (PaUnixThread *self)

Variables
pthread_t	paUnixMainThread

Macro Definition Documentation

PA_ASSERT_CALL

#define PA_ASSERT_CALL	(		expr,
			success )

Value:

    paUtilErr_ = (expr); \
    assert( success == paUtilErr_ );

Referenced by PaUnixMutex_Initialize(), PaUnixMutex_Terminate(), PaUnixThread_New(), and PaUnixThread_Terminate().

PA_ENSURE

#define PA_ENSURE

(

expr

)

Value:

PA_ENSURE_ON_ERROR(expr, goto error)

Referenced by PaAlsa_GetStreamInputCard(), PaAlsa_GetStreamOutputCard(), PaAlsa_Initialize(), PaOSS_Initialize(), PaUnixThread_New(), PaUnixThread_NotifyParent(), and PaUnixThread_PrepareNotify().

PA_ENSURE_NO_GOTO

#define PA_ENSURE_NO_GOTO

(

expr

)

Value:

PA_ENSURE_ON_ERROR(expr, (void)0)

PA_ENSURE_ON_ERROR

#define PA_ENSURE_ON_ERROR	(		expr,
			_on_error )

Value:

    do { \
        if( UNLIKELY( (paUtilErr_ = (expr)) < paNoError ) ) \
        { \
            PaUtil_DebugPrint(( "Expression '" #expr "' failed in '" __FILE__ "', line: " PA_STRINGIZE( __LINE__ ) "\n" )); \
            result = paUtilErr_; \
            _on_error; \
        } \
    } while (0);

PA_ENSURE_SYSTEM

#define PA_ENSURE_SYSTEM	(		expr,
			success )

Value:

    do { \
        if( UNLIKELY( (paUtilErr_ = (expr)) != success ) ) \
        { \
            /* PaUtil_SetLastHostErrorInfo should only be used in the main thread */ \
            if( pthread_equal(pthread_self(), paUnixMainThread) ) \
            { \
                PaUtil_SetLastHostErrorInfo( paALSA, paUtilErr_, strerror( paUtilErr_ ) ); \
            } \
            PaUtil_DebugPrint( "Expression '" #expr "' failed in '" __FILE__ "', line: " PA_STRINGIZE( __LINE__ ) "\n" ); \
            result = paUnanticipatedHostError; \
            goto error; \
        } \
    } while( 0 );

Referenced by PaUnixMutex_Lock(), PaUnixMutex_Unlock(), PaUnixThread_New(), and PaUnixThread_Terminate().

PA_MAX

#define PA_MAX	(		x,
			y )

Value:

( (x) > (y) ? (x) : (y) )

PA_MIN

#define PA_MIN	(		x,
			y )

Value:

( (x) < (y) ? (x) : (y) )

Referenced by PaUnixThread_New().

PA_UNLESS

#define PA_UNLESS	(		expr,
			code )

Value:

PA_UNLESS_ON_ERROR(expr, code, goto error)

Referenced by PaAlsa_GetStreamInputCard(), PaAlsa_GetStreamOutputCard(), PaAlsa_Initialize(), PaAudioIO_Initialize(), PaOSS_Initialize(), PaUnixThread_New(), PaUnixThread_NotifyParent(), PaUnixThread_PrepareNotify(), and PaUtil_InitializeDeviceInfo().

PA_UNLESS_NO_GOTO

#define PA_UNLESS_NO_GOTO	(		expr,
			code )

Value:

PA_UNLESS_ON_ERROR(expr, code, (void)0)

PA_UNLESS_ON_ERROR

#define PA_UNLESS_ON_ERROR	(		expr,
			code,
			_on_error )

Value:

    do { \
        if( UNLIKELY( (expr) == 0 ) ) \
        { \
            PaUtil_DebugPrint(( "Expression '" #expr "' failed in '" __FILE__ "', line: " PA_STRINGIZE( __LINE__ ) "\n" )); \
            result = (code); \
            _on_error; \
        } \
    } while (0);

PaUnixThreading_EXIT

#define PaUnixThreading_EXIT

(

result

)

Value:

    do { \
        PaError* pres = NULL; \
        if( paNoError != (result) ) \
        { \
            pres = malloc( sizeof (PaError) ); \
            *pres = (result); \
        } \
        pthread_exit( pres ); \
    } while (0);

Perish, passing on eventual error code.

A thin wrapper around pthread_exit, will automatically pass on any error code to the joining thread. If the result indicates an error, i.e. it is not equal to paNoError, this function will automatically allocate a pointer so the error is passed on with pthread_exit. If the result indicates that all is well however, only a NULL pointer will be handed to pthread_exit. Thus, the joining thread should check whether a non-NULL result pointer is obtained from pthread_join and make sure to free it.

Parameters

result

The error code to pass on to the joining thread.

UNLIKELY

#define UNLIKELY

(

expr

)

Value:

(expr)

Function Documentation

PaUnixMutex_Initialize()

PaError PaUnixMutex_Initialize

(

PaUnixMutex *

self

)

References PaUnixMutex::mtx, PA_ASSERT_CALL, and paNoError.

Referenced by PaUnixThread_New().

PaUnixMutex_Lock()

PaError PaUnixMutex_Lock

(

PaUnixMutex *

self

)

Lock mutex.

We're disabling thread cancellation while the thread is holding a lock, so mutexes are properly unlocked at termination time.

References PaUnixMutex::mtx, PA_ENSURE_SYSTEM, and paNoError.

Referenced by PaUnixThread_New(), PaUnixThread_NotifyParent(), and PaUnixThread_PrepareNotify().

PaUnixMutex_Terminate()

PaError PaUnixMutex_Terminate

(

PaUnixMutex *

self

)

References PaUnixMutex::mtx, PA_ASSERT_CALL, and paNoError.

Referenced by PaUnixThread_Terminate().

PaUnixMutex_Unlock()

PaError PaUnixMutex_Unlock

(

PaUnixMutex *

self

)

Unlock mutex.

Thread cancellation is enabled again after the mutex is properly unlocked.

References PaUnixMutex::mtx, PA_ENSURE_SYSTEM, and paNoError.

Referenced by PaUnixThread_New(), and PaUnixThread_NotifyParent().

PaUnixThread_New()

PaError PaUnixThread_New	(	PaUnixThread *	self,
		void *(*	threadFunc )(void *),
		void *	threadArg,
		PaTime	waitForChild,
		int	rtSched )

Spawn a thread.

Intended for spawning the callback thread from the main thread. This function can even block (for a certain time or indefinitely) until notified by the callback thread (using PaUnixThread_NotifyParent), which can be useful in order to make sure that callback has commenced before returning from Pa_StartStream.

Parameters

threadFunc	The function to be executed in the child thread.
waitForChild	If not 0, wait for child thread to call PaUnixThread_NotifyParent. Less than 0 means wait for ever, greater than 0 wait for the specified time.
rtSched	Enable realtime scheduling?

Returns

: If timed out waiting on child, paTimedOut.

References PaUnixThread::cond, PaUnixThread::condClockId, PaUnixMutex::mtx, PaUnixThread::mtx, PA_ASSERT_CALL, PA_DEBUG, PA_ENSURE, PA_ENSURE_SYSTEM, PA_MIN, PA_UNLESS, paInternalError, paNoError, PaPthreadUtil_GetTime(), PaPthreadUtil_NegotiateCondAttrClock(), PaUnixThread::parentWaiting, paTimedOut, PaUnixMutex_Initialize(), PaUnixMutex_Lock(), PaUnixMutex_Unlock(), PaUnixThread_Terminate(), PaUtil_GetTime(), and PaUnixThread::thread.

PaUnixThread_NotifyParent()

PaError PaUnixThread_NotifyParent

(

PaUnixThread *

self

)

Notify waiting parent thread.

Returns

: If parent timed out waiting, paTimedOut. If parent was never waiting, paInternalError.

References PaUnixThread::cond, PaUnixThread::locked, PaUnixThread::mtx, PA_ENSURE, PA_UNLESS, paInternalError, paNoError, PaUnixThread::parentWaiting, PaUnixMutex_Lock(), and PaUnixMutex_Unlock().

PaUnixThread_PrepareNotify()

PaError PaUnixThread_PrepareNotify

(

PaUnixThread *

self

)

Prepare to notify waiting parent thread.

An internal lock must be held before the parent is notified in PaUnixThread_NotifyParent, call this to acquire it beforehand.

Returns

: If parent is not waiting, paInternalError.

References PaUnixThread::locked, PaUnixThread::mtx, PA_ENSURE, PA_UNLESS, paInternalError, paNoError, PaUnixThread::parentWaiting, and PaUnixMutex_Lock().

PaUnixThread_StopRequested()

int PaUnixThread_StopRequested

(

PaUnixThread *

self

)

Has the parent thread requested this thread to stop?

References PaUnixThread::stopRequested.

PaUnixThread_Terminate()

PaError PaUnixThread_Terminate	(	PaUnixThread *	self,
		int	wait,
		PaError *	exitResult )

Terminate thread.

Parameters

wait	If true, request that background thread stop and wait until it does, else cancel it.
exitResult	If non-null this will upon return contain the exit status of the thread.

References PaUnixThread::cond, PaUnixThread::mtx, PA_ASSERT_CALL, PA_DEBUG, PA_ENSURE_SYSTEM, paNoError, PaUnixMutex_Terminate(), PaUnixThread::stopRequested, and PaUnixThread::thread.

Referenced by PaUnixThread_New().

PaUnixThreading_Initialize()

PaError PaUnixThreading_Initialize

(

void

)

Initialize global threading state.

References paNoError, and paUnixMainThread.

Referenced by PaAlsa_Initialize(), and PaAsiHpi_Initialize().

PaUtil_CancelThreading()

PaError PaUtil_CancelThreading	(	PaUtilThreading *	threading,
		int	wait,
		PaError *	exitResult )

References PaUtilThreading::callbackThread, and paNoError.

PaUtil_InitializeThreading()

PaError PaUtil_InitializeThreading

(

PaUtilThreading *

threading

)

References paNoError.

PaUtil_StartThreading()

PaError PaUtil_StartThreading	(	PaUtilThreading *	threading,
		void *(*	threadRoutine )(void *),
		void *	data )

References PaUtilThreading::callbackThread, and paNoError.

PaUtil_TerminateThreading()

void PaUtil_TerminateThreading

(

PaUtilThreading *

threading

)

Variable Documentation

paUnixMainThread

pthread_t paUnixMainThread

extern

Referenced by PaUnixThreading_Initialize().