/*
* Copyright (c) 2010 Ixonos Plc.
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - Initial contribution
*
* Contributors:
* Ixonos Plc
*
* Description:
* Header for thdwrap.cpp.
*
*/
#ifndef _MTXWRAP_H_
#define _MTXWRAP_H_
#include "nrctyp32.h"
typedef void *thdMutex_t;
typedef void *thdSyncObject_t;
typedef void *array_t;
typedef void *thdParamData_t;
#define THD_INFINITE -1
#define THD_TIMEOUT -1
#define THD_MESSAGE -2
/* If THD_DS not defined, define it as nothing */
#ifndef THD_DS
#define THD_DS
#endif
#if defined(__MARM__) && !defined(__stdcall)
#define __stdcall
#endif
/*
* Structs and typedefs
*/
/* This type is used in thdBeginThreadSync to pass the address
of the thread main function. */
typedef unsigned ( __stdcall *thdMainFunction_t )( void * );
/****************************************************************************\
*
* Function: thdMutex_t thdCreateMutex( void );
*
* Description: Allocates a mutex handle
*
* Returns: Newly created mutex
*
\****************************************************************************/
THD_DS thdMutex_t thdCreateMutex( void );
/****************************************************************************\
*
* Function: int thdDestroyMutex( thdMutex_t handle );
*
* Description: Deallocates a mutex handle
*
* Input: thdMutex_t handle Handle to be freed
*
* Returns: zero on success, negative on error
*
\****************************************************************************/
THD_DS int thdDestroyMutex( thdMutex_t handle );
/****************************************************************************\
*
* Function: int thdEnterMutex( thdMutex_t handle );
*
* Description: Enters a mutex
* When a mutex has been entered, it can not be entered by
* any other thread before the first one has left it.
* One thread can enter mutex many times ("nested"), but it
* must always leave the mutex the exactly same number of times.
*
* Input: thdMutex_t handle Mutex handle to enter
*
* Returns: zero on success, negative on error
*
\****************************************************************************/
THD_DS int thdEnterMutex( thdMutex_t handle );
#if(_WIN32_WINNT >= 0x0400)
/****************************************************************************\
*
* Function: int thdTryMutex( thdMutex_t handle );
*
* Description: Tries to enter a mutex, but does not wait to be able to enter
* Note: only available with WinNT 4.0 or above
*
* Input: thdMutex_t handle Mutex handle to enter
*
* Returns: 1 if entered, 0 if not entered, negative on error
*
\****************************************************************************/
THD_DS int thdTryMutex( thdMutex_t handle );
#endif
/****************************************************************************\
*
* Function: int thdLeaveMutex( thdMutex_t handle );
*
* Description: Leaves a mutex
*
* Input: thdMutex_t handle Mutex handle to leave
*
* Returns: zero on success, negative on error
*
\****************************************************************************/
THD_DS int thdLeaveMutex( thdMutex_t handle );
/****************************************************************************\
*
* Function: thdBeginThreadSync
* thdCreateThreadSync
*
* Description: Creates a thread with synchronization; ensures that a message
* queue exists for the thread immediately after returning from
* this function. The main function of the created thread MUST
* include a call to thdEnterThreadSync.
*
* The difference between thdBeginThreadSync and
* thdCreateThreadSync is the type of the routine parameter.
* If the function is passed as a data pointer (as in
* thdCreateThreadSync), the compiler should generate
* a warning since this is against ANSI-C. Thus, the usage of
* thdBeginThreadSync should be avoided.
*
* Input: routine Pointer to thread main function
* param Free-form parameter given to thread
* id Pointer to int to receive thread id
*
* Returns: Handle of the newly created thread, NULL for error
*
\****************************************************************************/
THD_DS void * thdBeginThreadSync( thdMainFunction_t routine,
void *param, u_int32 *id );
THD_DS void * thdCreateThreadSync( void *routine, void *param,
u_int32 *id );
/****************************************************************************\
*
* Function: void *thdEnterThreadSync( void *param );
*
* Description: Creates the message queue and signals the parent thread
* the completition.
*
* Input: void *param The parameter passed to the main
*
* Returns: The free-form parameter that was given to thdCreateThreadSync
*
\****************************************************************************/
THD_DS void * thdEnterThreadSync( void *param );
/****************************************************************************\
*
* Function: void thdExitThread( int exitcode );
*
* Description: Terminates the current thread with given exit code.
* Note! This function does not return.
* (WIN32) :: If thread does not call this function, small
* memory leaks will result
*
* Input: int exitcode Exit code for thread
*
\****************************************************************************/
THD_DS void thdExitThread( int exitcode );
/****************************************************************************\
*
* Function: void thdSetThreadPriority( void *thread, int priority );
*
* Description: Sets thread's priority
*
* Input: void *thread Thread to set
* int priority Priority number, from -3 to 3,
* 0 is normal priority.
*
\****************************************************************************/
THD_DS void thdSetThreadPriority( void *thread, int priority );
/****************************************************************************\
*
* Function: void thdTerminateThread( void *thread, int exitcode );
*
* Description: Terminates a thread immediately
*
* Input: void *thread Thread handle
* int exitcode Exit code for the thread
*
\****************************************************************************/
THD_DS void thdTerminateThread( void *thread, int exitcode );
/****************************************************************************\
*
* Function: thdSyncObject_t thdCreateEvent( void );
*
* Description: Creates an event
*
* Returns: Handle for the event
*
\****************************************************************************/
THD_DS thdSyncObject_t thdCreateEvent( void );
THD_DS thdSyncObject_t thdCreateEvent( array_t *array );
/****************************************************************************\
*
* Function: void thdDestroyEvent( thdSyncObject_t event );
*
* Description: Destroys an event
*
* Input: thdSyncObject_t event Event to be destroyed
*
\****************************************************************************/
THD_DS void thdDestroyEvent( thdSyncObject_t event );
/****************************************************************************\
*
* Function: void thdSetEvent( thdSyncObject_t event );
*
* Description: Sets (signals) an event
*
* Input: thdSyncObject_t event Event to set
*
\****************************************************************************/
THD_DS void thdSetEvent( thdSyncObject_t event );
/****************************************************************************\
*
* Function: void thdResetEvent( thdSyncObject_t event );
*
* Description: Resets (unsignals) an event
*
* Input: thdSyncObject_t event Event to reset
*
\****************************************************************************/
THD_DS void thdResetEvent( thdSyncObject_t event );
/****************************************************************************\
*
* Function: int thdWaitSyncObject( thdSyncObject_t event, int time );
*
* Description: Waits until the given event is signaled, or time limit elapses
*
* Input: thdSyncObject_t event Event handle to wait
* int time Time limit in ms, -1 = infinite
*
* Returns: Zero if event was signaled, -1 if time limit elapsed
*
\****************************************************************************/
THD_DS int thdWaitSyncObject( thdSyncObject_t event, int time );
/****************************************************************************\
*
* Function: int thdWaitManySyncObjects( thdSyncObject_t *events, int count, int time );
*
* Description: Waits until at least one of the given events is signaled, or
* time limit elapses
*
* Input: thdSyncObject_t *events Pointer to array of event handles
* int count Number of event handles in array
* int time Time limit in ms, -1 = infinite
*
* Returns: Index of event signaled (>=0) or
* THD_TIMEOUT if time limit elapsed
*
\****************************************************************************/
THD_DS int thdWaitManySyncObjects( thdSyncObject_t *events, int count, int time );
/****************************************************************************\
*
* Function: int thdWaitManySyncObjectsOrMessage( thdSyncObject_t *events, int count, int time )
*
* Description: Waits until at least one of the given synchronization objects
* is signaled, or the time limit elapses, or a message is posted
* to thread's message queue.
* You can give NULL to events and zero to count to only wait
* for messages.
*
* Input: thdSyncObject_t *events Pointer to array of sync. object handles
* int count Number of handles in array
* int time Time limit in ms, -1 = infinite
*
* Returns: Index of event signaled (>=0)
* THD_TIMEOUT if time limit elapsed
* THD_MESSAGE if a message was posted
*
\****************************************************************************/
THD_DS int thdWaitManySyncObjectsOrMessage( thdSyncObject_t *events, int count, int time );
/****************************************************************************\
*
* Function: thdSyncObject_t thdThreadToEvent( void *thread );
*
* Description: Converts a thread handle returned by thdCreateThread into an
* event handle that can be waited for with thdWaitSyncObject
* This event handle must not be closed!
*
* Input: void *thread Thread handle
*
* Returns: Event handle
*
\****************************************************************************/
THD_DS thdSyncObject_t thdThreadToEvent( void *thread );
/****************************************************************************\
*
* Function: thdSyncObject_t thdCreateSemaphore( int initcount, int maxcount );
*
* Description: Creates a semaphore object.
*
* Input: int initcount Initial count for semaphore
* int maxcount Maximum count
*
* Returns: Handle of the created semaphore
*
\****************************************************************************/
THD_DS thdSyncObject_t thdCreateSemaphore( int initcount, int maxcount );
THD_DS thdSyncObject_t thdCreateSemaphore( int initcount, int maxcount, array_t *array );
/****************************************************************************\
*
* Function: void thdDestroySemaphore( thdSyncObject_t handle );
*
* Description: Destroys a semaphore object
*
* Input: thdSyncObject_t handle Handle to close
*
\****************************************************************************/
THD_DS void thdDestroySemaphore( thdSyncObject_t handle );
/****************************************************************************\
*
* Function: void thdReleaseSemaphore( thdSyncObject_t handle, int count );
*
* Description: Releases a semaphore
*
* Input: thdSyncObject_t handle Semaphore to release
* int count Release count
*
* Returns: Previous count
*
\****************************************************************************/
THD_DS int thdReleaseSemaphore( thdSyncObject_t handle, int count );
/****************************************************************************\
*
* Function: void thdSleep( int time );
*
* Description: Enters an efficient wait state for a specified time
*
* Input: int time Time to sleep, in milliseconds
*
\****************************************************************************/
THD_DS void thdSleep( int time );
#endif
// End of File