jack/thread.h

   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 #ifndef __jack_thread_h__
  21 #define __jack_thread_h__
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 #include <pthread.h>
  28
  29 /* use 512KB stack per thread - the default is way too high to be feasible
  30  * with mlockall() on many systems */
  31 #define THREAD_STACK 524288
  32
  33 /** @file thread.h
  34  *
  35  * Library functions to standardize thread creation for JACK and its
  36  * clients.  These interfaces hide some system variations in the
  37  * handling of realtime scheduling and associated privileges.
  38  */
  39
  40 /**
  41  * @defgroup ClientThreads Creating and managing client threads
  42  * @{
  43  */
  44
  45 /**
  46  * @returns if JACK is running with realtime scheduling, this returns
  47  * the priority that any JACK-created client threads will run at.
  48  * Otherwise returns -1.
  49  */
  50
  51 int jack_client_real_time_priority (jack_client_t*);
  52
  53 /**
  54  * @returns if JACK is running with realtime scheduling, this returns
  55  * the maximum priority that a JACK client thread should use if the thread
  56  * is subject to realtime scheduling. Otherwise returns -1.
  57  */
  58
  59 int jack_client_max_real_time_priority (jack_client_t*);
  60
  61 /**
  62  * Attempt to enable realtime scheduling for a thread.  On some
  63  * systems that may require special privileges.
  64  *
  65  * @param thread POSIX thread ID.
  66  * @param priority requested thread priority.
  67  *
  68  * @returns 0, if successful; EPERM, if the calling process lacks
  69  * required realtime privileges; otherwise some other error number.
  70  */
  71 int jack_acquire_real_time_scheduling (pthread_t thread, int priority);
  72
  73 /**
  74  * Create a thread for JACK or one of its clients.  The thread is
  75  * created executing @a start_routine with @a arg as its sole
  76  * argument.
  77  *
  78  * @param client the JACK client for whom the thread is being created. May be
  79  * NULL if the client is being created within the JACK server.
  80  * @param thread place to return POSIX thread ID.
  81  * @param priority thread priority, if realtime.
  82  * @param realtime true for the thread to use realtime scheduling.  On
  83  * some systems that may require special privileges.
  84  * @param start_routine function the thread calls when it starts.
  85  * @param arg parameter passed to the @a start_routine.
  86  *
  87  * @returns 0, if successful; otherwise some error number.
  88  */
  89 int jack_client_create_thread (jack_client_t* client,
  90                                pthread_t *thread,
  91                                int priority,
  92                                int realtime,    /* boolean */
  93                                void *(*start_routine)(void*),
  94                                void *arg);
  95
  96 /**
  97  * Drop realtime scheduling for a thread.
  98  *
  99  * @param thread POSIX thread ID.
 100  *
 101  * @returns 0, if successful; otherwise an error number.
 102  */
 103 int jack_drop_real_time_scheduling (pthread_t thread);
 104
 105 /* @} */
 106
 107 #ifdef __cplusplus
 108 }
 109 #endif
 110
 111 #endif /* __jack_thread_h__ */