jack.c.thread source code

1 /*
2    Copyright (C) 2004 Paul Davis
3 
4    This program is free software; you can redistribute it and/or modify
5    it under the terms of the GNU Lesser General Public License as published by
6    the Free Software Foundation; either version 2.1 of the License, or
7    (at your option) any later version.
8 
9    This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    GNU Lesser General Public License for more details.
13 
14    You should have received a copy of the GNU Lesser General Public License
15    along with this program; if not, write to the Free Software
16    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
17 
18 */
19 
20 module jack.c.thread;
21 public import jack.c.systemdeps;
22 public import jack.c.types;
23 
24 extern (C)
25 {
26 
27 /* use 512KB stack per thread - the default is way too high to be feasible
28  * with mlockall() on many systems */
29 enum THREAD_STACK = 524288;
30 
31 /** @file thread.h
32  *
33  * Library functions to standardize thread creation for JACK and its
34  * clients.  These interfaces hide some system variations in the
35  * handling of realtime scheduling and associated privileges.
36  */
37 
38 /**
39  * @defgroup ClientThreads Creating and managing client threads
40  * @{
41  */
42 
43  /**
44  * @returns if JACK is running with realtime scheduling, this returns
45  * the priority that any JACK-created client threads will run at.
46  * Otherwise returns -1.
47  */
48 
49 int jack_client_real_time_priority (jack_client_t*) /* JACK_OPTIONAL_WEAK_EXPORT */;
50 
51 /**
52  * @returns if JACK is running with realtime scheduling, this returns
53  * the maximum priority that a JACK client thread should use if the thread
54  * is subject to realtime scheduling. Otherwise returns -1.
55  */
56 
57 int jack_client_max_real_time_priority (jack_client_t*) /* JACK_OPTIONAL_WEAK_EXPORT */;
58 
59 /**
60  * Attempt to enable realtime scheduling for a thread.  On some
61  * systems that may require special privileges.
62  *
63  * @param thread POSIX thread ID.
64  * @param priority requested thread priority.
65  *
66  * @returns 0, if successful; EPERM, if the calling process lacks
67  * required realtime privileges; otherwise some other error number.
68  */
69 int jack_acquire_real_time_scheduling (jack_native_thread_t thread, int priority) /* JACK_OPTIONAL_WEAK_EXPORT */;
70 
71 /**
72  * Create a thread for JACK or one of its clients.  The thread is
73  * created executing @a start_routine with @a arg as its sole
74  * argument.
75  *
76  * @param client the JACK client for whom the thread is being created. May be
77  * NULL if the client is being created within the JACK server.
78  * @param thread place to return POSIX thread ID.
79  * @param priority thread priority, if realtime.
80  * @param realtime true for the thread to use realtime scheduling.  On
81  * some systems that may require special privileges.
82  * @param start_routine function the thread calls when it starts.
83  * @param arg parameter passed to the @a start_routine.
84  *
85  * @returns 0, if successful; otherwise some error number.
86  */
87 int jack_client_create_thread (jack_client_t* client,
88                                jack_native_thread_t *thread,
89                                int priority,
90                                int realtime, 	/* boolean */
91                                void *function(void*) start_routine,
92                                void *arg) /* JACK_OPTIONAL_WEAK_EXPORT */;
93 
94 /**
95  * Drop realtime scheduling for a thread.
96  *
97  * @param thread POSIX thread ID.
98  *
99  * @returns 0, if successful; otherwise an error number.
100  */
101 int jack_drop_real_time_scheduling (jack_native_thread_t thread) /* JACK_OPTIONAL_WEAK_EXPORT */;
102 
103 /**
104  * Stop the thread, waiting for the thread handler to terminate.
105  *
106  * @param thread POSIX thread ID.
107  *
108  * @returns 0, if successful; otherwise an error number.
109  */
110 int jack_client_stop_thread(jack_client_t* client, jack_native_thread_t thread) /* JACK_OPTIONAL_WEAK_EXPORT */;
111 
112 /**
113  * Kill the thread.
114  *
115  * @param thread POSIX thread ID.
116  *
117  * @returns 0, if successful; otherwise an error number.
118  */
119  int jack_client_kill_thread(jack_client_t* client, jack_native_thread_t thread) /* JACK_OPTIONAL_WEAK_EXPORT */;
120 
121 version(Windows) {
122 } else {
123   import core.sys.posix.sys.types : pthread_t, pthread_attr_t;
124 
125  alias jack_thread_creator_t = int function(pthread_t*,
126                                             const(pthread_attr_t)*,
127 				            void* function(void*),
128 				            void* arg);
129 /**
130  * This function can be used in very very specialized cases
131  * where it is necessary that client threads created by JACK
132  * are created by something other than pthread_create(). After
133  * it is used, any threads that JACK needs for the client will
134  * will be created by calling the function passed to this
135  * function.
136  *
137  * No normal application/client should consider calling this.
138  * The specific case for which it was created involves running
139  * win32/x86 plugins under Wine on Linux, where it is necessary
140  * that all threads that might call win32 functions are known
141  * to Wine.
142  *
143  * Set it to NULL to restore thread creation function.
144  *
145  * @param creator a function that creates a new thread
146  *
147  */
148 void jack_set_thread_creator (jack_thread_creator_t creator) /* JACK_OPTIONAL_WEAK_EXPORT */;
149 
150 }
151 
152 /* @} */
153 
154 }