pa_unix_util.h File Reference

#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

Defines

#define PA_MIN(x, y)   ( (x) < (y) ? (x) : (y) )
#define PA_MAX(x, y)   ( (x) > (y) ? (x) : (y) )
#define UNLIKELY(expr)   (expr)
#define STRINGIZE_HELPER(expr)   #expr
#define STRINGIZE(expr)   STRINGIZE_HELPER(expr)
#define PA_UNLESS(expr, code)
#define PA_ENSURE(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 ()
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

Detailed Description


Define Documentation

#define PA_ASSERT_CALL ( expr,
success   ) 
Value:
paUtilErr_ = (expr); \
    assert( success == paUtilErr_ );

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

#define PA_ENSURE ( expr   ) 
Value:
do { \
        if( UNLIKELY( (paUtilErr_ = (expr)) < paNoError ) ) \
        { \
            PaUtil_DebugPrint(( "Expression '" #expr "' failed in '" __FILE__ "', line: " STRINGIZE( __LINE__ ) "\n" )); \
            result = paUtilErr_; \
            goto error; \
        } \
    } while (0);

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

#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: " STRINGIZE( __LINE__ ) "\n" ); \
            result = paUnanticipatedHostError; \
            goto error; \
        } \
    } while( 0 );

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

#define PA_MAX ( x,
 )     ( (x) > (y) ? (x) : (y) )
#define PA_MIN ( x,
 )     ( (x) < (y) ? (x) : (y) )

Referenced by PaUnixThread_New().

#define PA_UNLESS ( expr,
code   ) 
Value:
do { \
        if( UNLIKELY( (expr) == 0 ) ) \
        { \
            PaUtil_DebugPrint(( "Expression '" #expr "' failed in '" __FILE__ "', line: " STRINGIZE( __LINE__ ) "\n" )); \
            result = (code); \
            goto error; \
        } \
    } while (0);

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

#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.
#define STRINGIZE ( expr   )     STRINGIZE_HELPER(expr)
#define STRINGIZE_HELPER ( expr   )     #expr
#define UNLIKELY ( expr   )     (expr)

Function Documentation

PaError PaUnixMutex_Initialize ( PaUnixMutex self  ) 

References PA_ASSERT_CALL, and paNoError.

Referenced by PaUnixThread_New().

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 PA_ENSURE_SYSTEM, and paNoError.

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

PaError PaUnixMutex_Terminate ( PaUnixMutex self  ) 

References PA_ASSERT_CALL, and paNoError.

Referenced by PaUnixThread_Terminate().

PaError PaUnixMutex_Unlock ( PaUnixMutex self  ) 

Unlock mutex.

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

References PA_ENSURE_SYSTEM, and paNoError.

Referenced by PaUnixThread_New(), and PaUnixThread_NotifyParent().

PaError PaUnixThread_New ( PaUnixThread self,
void *(*)(void *)  threadFunc,
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) untill 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 PA_ASSERT_CALL, PA_DEBUG, PA_ENSURE, PA_ENSURE_SYSTEM, PA_MIN, PA_UNLESS, paInternalError, paNoError, paTimedOut, PaUnixMutex_Initialize(), PaUnixMutex_Lock(), PaUnixMutex_Unlock(), PaUnixThread_Terminate(), and PaUtil_GetTime().

PaError PaUnixThread_NotifyParent ( PaUnixThread self  ) 

Notify waiting parent thread.

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

References PA_ENSURE, PA_UNLESS, paInternalError, paNoError, PaUnixMutex_Lock(), and PaUnixMutex_Unlock().

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 PA_ENSURE, PA_UNLESS, paInternalError, paNoError, and PaUnixMutex_Lock().

int PaUnixThread_StopRequested ( PaUnixThread self  ) 

Has the parent thread requested this thread to stop?

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

Terminate thread.

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

References PA_ASSERT_CALL, PA_DEBUG, PA_ENSURE_SYSTEM, paNoError, and PaUnixMutex_Terminate().

Referenced by PaUnixThread_New().

PaError PaUnixThreading_Initialize (  ) 

Initialize global threading state.

References paNoError.

Referenced by PaAlsa_Initialize(), and PaAsiHpi_Initialize().

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

References paNoError.

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

Variable Documentation

pthread_t paUnixMainThread

Generated for PortAudio by  doxygen1.6.1