thread.h 4.94 KB
Newer Older
sletz's avatar
sletz committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
/*
   Copyright (C) 2004 Paul Davis

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License as published by
   the Free Software Foundation; either version 2.1 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

*/

#ifndef __jack_thread_h__
#define __jack_thread_h__

#ifdef __cplusplus
extern "C"
{
#endif

28
#include <jack/systemdeps.h>
sletz's avatar
sletz committed
29
#include <jack/weakmacros.h>
sletz's avatar
sletz committed
30

31
32
33
34
35
36
/** @file thread.h
 *
 * Library functions to standardize thread creation for JACK and its
 * clients.  These interfaces hide some system variations in the
 * handling of realtime scheduling and associated privileges.
 */
sletz's avatar
sletz committed
37

38
39
40
41
/**
 * @defgroup ClientThreads Creating and managing client threads
 * @{
 */
sletz's avatar
sletz committed
42

43
44
 /**
 * @returns if JACK is running with realtime scheduling, this returns
sletz's avatar
sletz committed
45
 * the priority that any JACK-created client threads will run at.
46
47
48
 * Otherwise returns -1.
 */

sletz's avatar
sletz committed
49
int jack_client_real_time_priority (jack_client_t*) JACK_OPTIONAL_WEAK_EXPORT;
50
51
52
53
54
55
56

/**
 * @returns if JACK is running with realtime scheduling, this returns
 * the maximum priority that a JACK client thread should use if the thread
 * is subject to realtime scheduling. Otherwise returns -1.
 */

sletz's avatar
sletz committed
57
int jack_client_max_real_time_priority (jack_client_t*) JACK_OPTIONAL_WEAK_EXPORT;
58
59
60
61
62
63
64
65
66
67
68

/**
 * Attempt to enable realtime scheduling for a thread.  On some
 * systems that may require special privileges.
 *
 * @param thread POSIX thread ID.
 * @param priority requested thread priority.
 *
 * @returns 0, if successful; EPERM, if the calling process lacks
 * required realtime privileges; otherwise some other error number.
 */
sletz's avatar
sletz committed
69
int jack_acquire_real_time_scheduling (pthread_t thread, int priority) JACK_OPTIONAL_WEAK_EXPORT;
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

/**
 * Create a thread for JACK or one of its clients.  The thread is
 * created executing @a start_routine with @a arg as its sole
 * argument.
 *
 * @param client the JACK client for whom the thread is being created. May be
 * NULL if the client is being created within the JACK server.
 * @param thread place to return POSIX thread ID.
 * @param priority thread priority, if realtime.
 * @param realtime true for the thread to use realtime scheduling.  On
 * some systems that may require special privileges.
 * @param start_routine function the thread calls when it starts.
 * @param arg parameter passed to the @a start_routine.
 *
 * @returns 0, if successful; otherwise some error number.
 */
int jack_client_create_thread (jack_client_t* client,
                               pthread_t *thread,
                               int priority,
                               int realtime, 	/* boolean */
                               void *(*start_routine)(void*),
sletz's avatar
sletz committed
92
                               void *arg) JACK_OPTIONAL_WEAK_EXPORT;
93
94
95
96
97
98
99
100

/**
 * Drop realtime scheduling for a thread.
 *
 * @param thread POSIX thread ID.
 *
 * @returns 0, if successful; otherwise an error number.
 */
sletz's avatar
sletz committed
101
int jack_drop_real_time_scheduling (pthread_t thread) JACK_OPTIONAL_WEAK_EXPORT;
102
103
104
105
106
107
108
109

/**
 * Stop the thread, waiting for the thread handler to terminate.
 *
 * @param thread POSIX thread ID.
 *
 * @returns 0, if successful; otherwise an error number.
 */
sletz's avatar
sletz committed
110
int jack_client_stop_thread(jack_client_t* client, pthread_t thread) JACK_OPTIONAL_WEAK_EXPORT;
111
112
113
114
115
116
117

/**
 * Cancel the thread then waits for the thread handler to terminate.
 *
 * @param thread POSIX thread ID.
 *
 * @returns 0, if successful; otherwise an error number.
sletz's avatar
sletz committed
118
 */
sletz's avatar
sletz committed
119
 int jack_client_kill_thread(jack_client_t* client, pthread_t thread) JACK_OPTIONAL_WEAK_EXPORT;
120
121

#ifndef WIN32
122

123
124
125
126
127
128
129
130
131
132
 typedef int (*jack_thread_creator_t)(pthread_t*,
				     const pthread_attr_t*,
				     void* (*function)(void*),
				     void* arg);
/**
 * This function can be used in very very specialized cases
 * where it is necessary that client threads created by JACK
 * are created by something other than pthread_create(). After
 * it is used, any threads that JACK needs for the client will
 * will be created by calling the function passed to this
sletz's avatar
sletz committed
133
 * function.
134
135
136
137
138
139
 *
 * No normal application/client should consider calling this.
 * The specific case for which it was created involves running
 * win32/x86 plugins under Wine on Linux, where it is necessary
 * that all threads that might call win32 functions are known
 * to Wine.
sletz's avatar
sletz committed
140
 *
141
142
 * Set it to NULL to restore thread creation function.
 *
143
 * @param creator a function that creates a new thread
sletz's avatar
sletz committed
144
 *
145
 */
sletz's avatar
sletz committed
146
void jack_set_thread_creator (jack_thread_creator_t creator) JACK_OPTIONAL_WEAK_EXPORT;
147

sletz's avatar
sletz committed
148
#endif
149

150
/* @} */
sletz's avatar
sletz committed
151
152
153
154
155
156

#ifdef __cplusplus
}
#endif

#endif /* __jack_thread_h__ */