| ARX 1.0 The next-generation open source augmented reality toolkit.

Loading...
Searching...
No Matches
thread_sub.h
Go to the documentation of this file.
1/*
2 * thread_sub.h
3 * artoolkitX
4 *
5 * Implements a basic client-worker threading system.
6 *
7 * This file is part of artoolkitX.
8 *
9 * artoolkitX is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Lesser General Public License as published by
11 * the Free Software Foundation, either version 3 of the License, or
12 * (at your option) any later version.
13 *
14 * artoolkitX is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with artoolkitX. If not, see <http://www.gnu.org/licenses/>.
21 *
22 * As a special exception, the copyright holders of this library give you
23 * permission to link this library with independent modules to produce an
24 * executable, regardless of the license terms of these independent modules, and to
25 * copy and distribute the resulting executable under terms of your choice,
26 * provided that you also meet, for each linked independent module, the terms and
27 * conditions of the license of that module. An independent module is a module
28 * which is neither derived from nor based on this library. If you modify this
29 * library, you may extend this exception to your version of the library, but you
30 * are not obligated to do so. If you do not wish to do so, delete this exception
31 * statement from your version.
32 *
33 * Copyright 2018 Realmax, Inc.
34 * Copyright 2015 Daqri, LLC.
35 * Copyright 2007-2015 ARToolworks, Inc.
36 *
37 * Author(s): Hirokazu Kato, Philip Lamb
38 *
39 */
40/*
41 thread_sub.c, thread_sub.h
42
43 Written by Hirokazu Kato
44 kato@is.naist.jp Apr.24 2007
45 */
46
47#ifndef __ARUtil_thread_sub_h__
48#define __ARUtil_thread_sub_h__
49
50#include <ARX/ARUtil/types.h>
51
52#ifdef __cplusplus
53 extern "C" {
54#endif
55
56 typedef struct _THREAD_HANDLE_T THREAD_HANDLE_T;
57
58//
59// Client-side.
60//
61
62// Setup.
63 ARUTIL_EXTERN THREAD_HANDLE_T *threadInit( int ID, void *arg, void *(*start_routine)(THREAD_HANDLE_T*) ); // Create a new thread, and launch start_routine() on it. Returns NULL in case of failure.
64 ARUTIL_EXTERN int threadFree( THREAD_HANDLE_T **flag ); // Frees structures associated with the thread handle pointed to by the location pointed to by flag. Thread should already have terminated (i.e. threadWaitQuit() has returned). Location pointed to by flag is set to NULL.
65
66// Communication.
67 ARUTIL_EXTERN int threadStartSignal( THREAD_HANDLE_T *flag ); // Send the worker thread the "start processing" request.
68 ARUTIL_EXTERN int threadGetStatus( THREAD_HANDLE_T *flag ); // Find out (without waiting) whether a worker has ended. 0 = not started or started but not yet ended, 1 = ended.
69 ARUTIL_EXTERN int threadGetBusyStatus( THREAD_HANDLE_T *flag ); // Find out if a worker is currently busy. 0 = worker not started or worker ended, 1 = worker started but not yet ended.
70 ARUTIL_EXTERN int threadEndWait( THREAD_HANDLE_T *flag ); // Wait for thread to end processing.
71 ARUTIL_EXTERN int threadWaitQuit( THREAD_HANDLE_T *flag ); // Tell a thread waiting for the "start processing" request to quit (exit), and wait until this has happened.
72
73// Example client structure:
74//
75// THREAD_HANDLE_T *threadHandle = threadInit(0, NULL, worker);
76// if (!threadHandle) {
77// fprintf(stderr, "Error starting thread.\n");
78// exit(-1);
79// }
80//
81// // Ready to do some work:
82// threadStartSignal(threadHandle);
83//
84// // Wait for the results.
85// threadEndWait(threadHandle);
86//
87// // If all done, quit and cleanup.
88// threadWaitQuit(threadHandle);
89// threadFree(&threadHandle);
90
91//
92// Worker-side.
93//
94
95 ARUTIL_EXTERN int threadStartWait( THREAD_HANDLE_T *flag ); // Wait for the "start processing" request. Returns 0 if worker should start, or -1 if worker should quit (exit).
96 ARUTIL_EXTERN int threadEndSignal( THREAD_HANDLE_T *flag ); // Notify anyone waiting that the worker has ended.
97 ARUTIL_EXTERN int threadGetID( THREAD_HANDLE_T *flag ); // Get the 'ID' value passed to the thread's start routine.
98 ARUTIL_EXTERN void *threadGetArg( THREAD_HANDLE_T *flag ); // Get the 'arg' value passed to the thread's start routine.
99
100// Example worker structure:
101//
102// void *worker(THREAD_HANDLE_T *threadHandle)
103// {
104// void *arg = threadHandle->arg; // Get data passed to the worker.
105// while (threadStartWait(threadHandle) == 0) {
106// // Do work, probably on arg.
107// threadEndSignal(threadHandle);
108// }
109// // Do cleanup.
110// return (NULL);
111// }
112
113 ARUTIL_EXTERN int threadGetCPU(void); // Returns the number of online CPUs in the system.
114
115
116#ifdef __cplusplus
117}
118#endif
119#endif // !__ARUtil_thread_sub_h__
_THREAD_HANDLE_T
Definition: thread_sub.c:78
_THREAD_HANDLE_T::arg
void * arg
Definition: thread_sub.c:87
_THREAD_HANDLE_T::ID
int ID
Definition: thread_sub.c:79
threadWaitQuit
ARUTIL_EXTERN int threadWaitQuit(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:247
threadGetCPU
ARUTIL_EXTERN int threadGetCPU(void)
Definition: thread_sub.c:258
threadEndWait
ARUTIL_EXTERN int threadEndWait(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:236
threadGetBusyStatus
ARUTIL_EXTERN int threadGetBusyStatus(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:226
threadInit
ARUTIL_EXTERN THREAD_HANDLE_T * threadInit(int ID, void *arg, void *(*start_routine)(THREAD_HANDLE_T *))
Definition: thread_sub.c:152
threadFree
ARUTIL_EXTERN int threadFree(THREAD_HANDLE_T **flag)
Definition: thread_sub.c:197
threadStartWait
ARUTIL_EXTERN int threadStartWait(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:94
threadStartSignal
ARUTIL_EXTERN int threadStartSignal(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:207
threadGetStatus
ARUTIL_EXTERN int threadGetStatus(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:216
threadGetID
ARUTIL_EXTERN int threadGetID(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:124
threadGetArg
ARUTIL_EXTERN void * threadGetArg(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:129
threadEndSignal
ARUTIL_EXTERN int threadEndSignal(THREAD_HANDLE_T *flag)
Definition: thread_sub.c:114
types.h
ARUTIL_EXTERN
#define ARUTIL_EXTERN
Definition: types.h:58