thread.h 4.71 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

30
31
32
33
34
35
/** @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
36

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

42
43
 /**
 * @returns if JACK is running with realtime scheduling, this returns
sletz's avatar
sletz committed
44
 * the priority that any JACK-created client threads will run at.
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 * Otherwise returns -1.
 */

int jack_client_real_time_priority (jack_client_t*);

/**
 * @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.
 */

int jack_client_max_real_time_priority (jack_client_t*);

/**
 * 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.
 */
int jack_acquire_real_time_scheduling (pthread_t thread, int priority);

/**
 * 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*),
                               void *arg);

/**
 * Drop realtime scheduling for a thread.
 *
 * @param thread POSIX thread ID.
 *
 * @returns 0, if successful; otherwise an error number.
 */
int jack_drop_real_time_scheduling (pthread_t thread);

/**
 * Stop the thread, waiting for the thread handler to terminate.
 *
 * @param thread POSIX thread ID.
 *
 * @returns 0, if successful; otherwise an error number.
 */
int jack_client_stop_thread(jack_client_t* client, pthread_t thread);

/**
 * 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
117
 */
118
 int jack_client_kill_thread(jack_client_t* client, pthread_t thread);
sletz's avatar
sletz committed
119
120

#ifndef WIN32
sletz's avatar
sletz committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

 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
 * function.
 *
 * 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
 * Set it to NULL to restore thread creation function.
 *
sletz's avatar
sletz committed
142
143
144
 * @param creator a function that creates a new thread
 *
 */
sletz's avatar
sletz committed
145
146
void jack_set_thread_creator (jack_thread_creator_t creator);

sletz's avatar
sletz committed
147
#endif
148
149

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

#ifdef __cplusplus
}
#endif

#endif /* __jack_thread_h__ */