common/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    $Id: thread.h,v 1.1.2.2 2006/06/20 14:44:00 letz Exp $
  19 */
  20
  21 #ifndef __jack_thread_h__
  22 #define __jack_thread_h__
  23
  24 #ifdef __cplusplus
  25 extern "C"
  26 {
  27 #endif
  28
  29 #ifdef WIN32
  30         #include <windows.h>
  31     typedef HANDLE pthread_t;
  32 #else
  33         #include <pthread.h>
  34 #endif
  35
  36
  37     /** @file thread.h
  38      *
  39      * Library functions to standardize thread creation for JACK and its
  40      * clients.  These interfaces hide some system variations in the
  41      * handling of realtime scheduling and associated privileges.
  42      */
  43
  44     /**
  45      * Attempt to enable realtime scheduling for a thread.  On some
  46      * systems that may require special privileges.
  47      *
  48      * @param thread POSIX thread ID.
  49      * @param priority requested thread priority.
  50      *
  51      * @returns 0, if successful; EPERM, if the calling process lacks
  52      * required realtime privileges; otherwise some other error number.
  53      */
  54     int jack_acquire_real_time_scheduling (pthread_t thread, int priority);
  55
  56     /**
  57      * Create a thread for JACK or one of its clients.  The thread is
  58      * created executing @a start_routine with @a arg as its sole
  59      * argument.
  60      *
  61      * @param client the JACK client for whom the thread is being created. May be
  62      * NULL if the client is being created within the JACK server.
  63      * @param thread place to return POSIX thread ID.
  64      * @param priority thread priority, if realtime.
  65      * @param realtime true for the thread to use realtime scheduling.  On
  66      * some systems that may require special privileges.
  67      * @param start_routine function the thread calls when it starts.
  68      * @param arg parameter passed to the @a start_routine.
  69      *
  70      * @returns 0, if successful; otherwise some error number.
  71      */
  72     int jack_client_create_thread (jack_client_t* client,
  73                                    pthread_t *thread,
  74                                    int priority,
  75                                    int realtime,        /* boolean */
  76                                    void *(*start_routine)(void*),
  77                                    void *arg);
  78
  79     /**
  80      * Drop realtime scheduling for a thread.
  81      *
  82      * @param thread POSIX thread ID.
  83      *
  84      * @returns 0, if successful; otherwise an error number.
  85      */
  86     int jack_drop_real_time_scheduling (pthread_t thread);
  87
  88 #ifdef __cplusplus
  89 }
  90 #endif
  91
  92 #endif /* __jack_thread_h__ */