1 /*

     2 * Copyright (c) 2010 Ixonos Plc.

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - Initial contribution

    11 *

    12 * Contributors:

    13 * Ixonos Plc

    14 *

    15 * Description:  

    16 * Header for thdwrap.cpp.

    17 *

    18 */

    19 

    20 

    21 

    22 #ifndef _MTXWRAP_H_

    23 #define _MTXWRAP_H_

    24 

    25 #include "nrctyp32.h"

    26 

    27 typedef void *thdMutex_t;

    28 typedef void *thdSyncObject_t;

    29 typedef void *array_t;

    30 typedef void *thdParamData_t;

    31 

    32 

    33 #define THD_INFINITE -1

    34 #define THD_TIMEOUT  -1

    35 #define THD_MESSAGE  -2

    36 

    37 /* If THD_DS not defined, define it as nothing */

    38 #ifndef THD_DS

    39 #define THD_DS

    40 #endif

    41 

    42 #if defined(__MARM__) && !defined(__stdcall)

    43 #define __stdcall

    44 #endif

    45 

    46 /* 

    47  * Structs and typedefs

    48  */

    49 

    50 /* This type is used in thdBeginThreadSync to pass the address

    51    of the thread main function. */

    52 typedef unsigned ( __stdcall *thdMainFunction_t )( void * );

    53 

    54 

    55 /****************************************************************************\

    56 *

    57 * Function:     thdMutex_t thdCreateMutex( void );

    58 *

    59 * Description:  Allocates a mutex handle

    60 *

    61 * Returns:      Newly created mutex

    62 *

    63 \****************************************************************************/

    64 

    65 THD_DS thdMutex_t thdCreateMutex( void );

    66 

    67 /****************************************************************************\

    68 *

    69 * Function:     int thdDestroyMutex( thdMutex_t handle );

    70 *

    71 * Description:  Deallocates a mutex handle

    72 *

    73 * Input:        thdMutex_t handle      Handle to be freed

    74 *

    75 * Returns:      zero on success, negative on error

    76 *

    77 \****************************************************************************/

    78 

    79 THD_DS int thdDestroyMutex( thdMutex_t handle );

    80 

    81 /****************************************************************************\

    82 *

    83 * Function:     int thdEnterMutex( thdMutex_t handle );

    84 *

    85 * Description:  Enters a mutex

    86 *               When a mutex has been entered, it can not be entered by

    87 *               any other thread before the first one has left it.

    88 *               One thread can enter mutex many times ("nested"), but it

    89 *               must always leave the mutex the exactly same number of times.

    90 *

    91 * Input:        thdMutex_t handle      Mutex handle to enter

    92 *

    93 * Returns:      zero on success, negative on error

    94 *

    95 \****************************************************************************/

    96 

    97 THD_DS int thdEnterMutex( thdMutex_t handle );

    98 

    99 #if(_WIN32_WINNT >= 0x0400)

   100 /****************************************************************************\

   101 *

   102 * Function:     int thdTryMutex( thdMutex_t handle );

   103 *

   104 * Description:  Tries to enter a mutex, but does not wait to be able to enter

   105 *               Note: only available with WinNT 4.0 or above

   106 *

   107 * Input:        thdMutex_t handle      Mutex handle to enter

   108 *

   109 * Returns:      1 if entered, 0 if not entered, negative on error

   110 *

   111 \****************************************************************************/

   112 

   113 THD_DS int thdTryMutex( thdMutex_t handle );

   114 #endif

   115 

   116 /****************************************************************************\

   117 *

   118 * Function:     int thdLeaveMutex( thdMutex_t handle );

   119 *

   120 * Description:  Leaves a mutex

   121 *

   122 * Input:        thdMutex_t handle      Mutex handle to leave

   123 *

   124 * Returns:      zero on success, negative on error

   125 *

   126 \****************************************************************************/

   127 

   128 THD_DS int thdLeaveMutex( thdMutex_t handle );

   129 

   130 /****************************************************************************\

   131 *

   132 * Function:     thdBeginThreadSync

   133 *               thdCreateThreadSync

   134 *

   135 * Description:  Creates a thread with synchronization; ensures that a message

   136 *               queue exists for the thread immediately after returning from

   137 *               this function. The main function of the created thread MUST

   138 *               include a call to thdEnterThreadSync.

   139 *

   140 *               The difference between thdBeginThreadSync and 

   141 *               thdCreateThreadSync is the type of the routine parameter.

   142 *               If the function is passed as a data pointer (as in

   143 *               thdCreateThreadSync), the compiler should generate

   144 *               a warning since this is against ANSI-C. Thus, the usage of

   145 *               thdBeginThreadSync should be avoided.

   146 *

   147 * Input:        routine             Pointer to thread main function

   148 *               param               Free-form parameter given to thread

   149 *               id                  Pointer to int to receive thread id

   150 *

   151 * Returns:      Handle of the newly created thread, NULL for error

   152 *

   153 \****************************************************************************/

   154 

   155 THD_DS void * thdBeginThreadSync( thdMainFunction_t routine, 

   156    void *param, u_int32 *id );

   157 THD_DS void * thdCreateThreadSync( void *routine, void *param, 

   158    u_int32 *id );

   159 

   160 /****************************************************************************\

   161 *

   162 * Function:     void *thdEnterThreadSync( void *param );

   163 *

   164 * Description:  Creates the message queue and signals the parent thread

   165 *               the completition.

   166 *

   167 * Input:        void *param             The parameter passed to the main

   168 *

   169 * Returns:      The free-form parameter that was given to thdCreateThreadSync

   170 *

   171 \****************************************************************************/

   172 

   173 THD_DS void * thdEnterThreadSync( void *param );

   174 

   175 /****************************************************************************\

   176 *

   177 * Function:     void thdExitThread( int exitcode );

   178 *

   179 * Description:  Terminates the current thread with given exit code.

   180 *               Note! This function does not return.

   181 *               (WIN32) :: If thread does not call this function, small

   182 *                          memory leaks will result

   183 *

   184 * Input:        int exitcode            Exit code for thread

   185 *

   186 \****************************************************************************/

   187 

   188 THD_DS void thdExitThread( int exitcode );

   189 

   190 /****************************************************************************\

   191 *

   192 * Function:     void thdSetThreadPriority( void *thread, int priority );

   193 *

   194 * Description:  Sets thread's priority

   195 *

   196 * Input:        void *thread            Thread to set

   197 *               int priority            Priority number, from -3 to 3,

   198 *                                       0 is normal priority.

   199 *

   200 \****************************************************************************/

   201 

   202 THD_DS void thdSetThreadPriority( void *thread, int priority );

   203 

   204 /****************************************************************************\

   205 *

   206 * Function:     void thdTerminateThread( void *thread, int exitcode );

   207 *

   208 * Description:  Terminates a thread immediately

   209 *

   210 * Input:        void *thread            Thread handle

   211 *               int exitcode            Exit code for the thread

   212 *

   213 \****************************************************************************/

   214 

   215 THD_DS void thdTerminateThread( void *thread, int exitcode );

   216 

   217 /****************************************************************************\

   218 *

   219 * Function:     thdSyncObject_t thdCreateEvent( void );

   220 *

   221 * Description:  Creates an event

   222 *

   223 * Returns:      Handle for the event

   224 *

   225 \****************************************************************************/

   226 

   227 THD_DS thdSyncObject_t thdCreateEvent( void );

   228 THD_DS thdSyncObject_t thdCreateEvent( array_t *array );

   229 

   230 /****************************************************************************\

   231 *

   232 * Function:     void thdDestroyEvent( thdSyncObject_t event );

   233 *

   234 * Description:  Destroys an event

   235 *

   236 * Input:        thdSyncObject_t event        Event to be destroyed

   237 *

   238 \****************************************************************************/

   239 

   240 THD_DS void thdDestroyEvent( thdSyncObject_t event );

   241 

   242 /****************************************************************************\

   243 *

   244 * Function:     void thdSetEvent( thdSyncObject_t event );

   245 *

   246 * Description:  Sets (signals) an event

   247 *

   248 * Input:        thdSyncObject_t event        Event to set

   249 *

   250 \****************************************************************************/

   251 

   252 THD_DS void thdSetEvent( thdSyncObject_t event );

   253 

   254 /****************************************************************************\

   255 *

   256 * Function:     void thdResetEvent( thdSyncObject_t event );

   257 *

   258 * Description:  Resets (unsignals) an event

   259 *

   260 * Input:        thdSyncObject_t event        Event to reset

   261 *

   262 \****************************************************************************/

   263 

   264 THD_DS void thdResetEvent( thdSyncObject_t event );

   265 

   266 /****************************************************************************\

   267 *

   268 * Function:     int thdWaitSyncObject( thdSyncObject_t event, int time );

   269 *

   270 * Description:  Waits until the given event is signaled, or time limit elapses

   271 *

   272 * Input:        thdSyncObject_t event        Event handle to wait

   273 *               int time                Time limit in ms, -1 = infinite

   274 *

   275 * Returns:      Zero if event was signaled, -1 if time limit elapsed

   276 *

   277 \****************************************************************************/

   278 

   279 THD_DS int thdWaitSyncObject( thdSyncObject_t event, int time );

   280 

   281 /****************************************************************************\

   282 *

   283 * Function:     int thdWaitManySyncObjects( thdSyncObject_t *events, int count, int time );

   284 *

   285 * Description:  Waits until at least one of the given events is signaled, or

   286 *               time limit elapses

   287 *

   288 * Input:        thdSyncObject_t *events Pointer to array of event handles

   289 *               int count               Number of event handles in array

   290 *               int time                Time limit in ms, -1 = infinite

   291 *

   292 * Returns:      Index of event signaled (>=0) or

   293 *               THD_TIMEOUT if time limit elapsed

   294 *

   295 \****************************************************************************/

   296 

   297 THD_DS int thdWaitManySyncObjects( thdSyncObject_t *events, int count, int time );

   298 

   299 /****************************************************************************\

   300 *

   301 * Function:     int thdWaitManySyncObjectsOrMessage( thdSyncObject_t *events, int count, int time )

   302 *

   303 * Description:  Waits until at least one of the given synchronization objects

   304 *               is signaled, or the time limit elapses, or a message is posted

   305 *               to thread's message queue.

   306 *               You can give NULL to events and zero to count to only wait

   307 *               for messages.

   308 *

   309 * Input:        thdSyncObject_t *events Pointer to array of sync. object handles

   310 *               int count               Number of handles in array

   311 *               int time                Time limit in ms, -1 = infinite

   312 *

   313 * Returns:      Index of event signaled (>=0)

   314 *               THD_TIMEOUT if time limit elapsed

   315 *               THD_MESSAGE if a message was posted

   316 *

   317 \****************************************************************************/

   318 

   319 THD_DS int thdWaitManySyncObjectsOrMessage( thdSyncObject_t *events, int count, int time );

   320 

   321 /****************************************************************************\

   322 *

   323 * Function:     thdSyncObject_t thdThreadToEvent( void *thread );

   324 *

   325 * Description:  Converts a thread handle returned by thdCreateThread into an

   326 *               event handle that can be waited for with thdWaitSyncObject

   327 *               This event handle must not be closed!

   328 *

   329 * Input:        void *thread            Thread handle

   330 *

   331 * Returns:      Event handle

   332 *

   333 \****************************************************************************/

   334 

   335 THD_DS thdSyncObject_t thdThreadToEvent( void *thread );

   336 

   337 /****************************************************************************\

   338 *

   339 * Function:     thdSyncObject_t thdCreateSemaphore( int initcount, int maxcount );

   340 *

   341 * Description:  Creates a semaphore object.

   342 *

   343 * Input:        int initcount           Initial count for semaphore

   344 *               int maxcount            Maximum count

   345 *

   346 * Returns:      Handle of the created semaphore

   347 *

   348 \****************************************************************************/

   349 

   350 THD_DS thdSyncObject_t thdCreateSemaphore( int initcount, int maxcount );

   351 THD_DS thdSyncObject_t thdCreateSemaphore( int initcount, int maxcount, array_t *array );

   352 

   353 /****************************************************************************\

   354 *

   355 * Function:     void thdDestroySemaphore( thdSyncObject_t handle );

   356 *

   357 * Description:  Destroys a semaphore object

   358 *

   359 * Input:        thdSyncObject_t handle  Handle to close

   360 *

   361 \****************************************************************************/

   362 

   363 THD_DS void thdDestroySemaphore( thdSyncObject_t handle );

   364 

   365 /****************************************************************************\

   366 *

   367 * Function:     void thdReleaseSemaphore( thdSyncObject_t handle, int count );

   368 *

   369 * Description:  Releases a semaphore

   370 *

   371 * Input:        thdSyncObject_t handle  Semaphore to release

   372 *               int count               Release count

   373 *

   374 * Returns:      Previous count

   375 *

   376 \****************************************************************************/

   377 

   378 THD_DS int thdReleaseSemaphore( thdSyncObject_t handle, int count );

   379 

   380 /****************************************************************************\

   381 *

   382 * Function:     void thdSleep( int time );

   383 *

   384 * Description:  Enters an efficient wait state for a specified time

   385 *

   386 * Input:        int time                Time to sleep, in milliseconds

   387 *

   388 \****************************************************************************/

   389 

   390 THD_DS void thdSleep( int time );

   391 

   392 #endif

   393 // End of File