Commit 48b51efd authored by sletz's avatar sletz
Browse files

Synchronize jack.h with JACK1, use jack_native_thread_t type in POSIX and OSX...

Synchronize jack.h with JACK1, use jack_native_thread_t type in POSIX and OSX thread implementation.

git-svn-id: http://subversion.jackaudio.org/jack/jack2/trunk/jackmp@4146 0c269be4-1314-0410-8aa9-9f06e86f4224
parent ab32fa70
......@@ -12,7 +12,7 @@ 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
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
......@@ -116,17 +116,17 @@ int JackDebugClient::Close()
void JackDebugClient::CheckClient(const char* function_name) const
{
*fStream << "CheckClient : " << function_name << ", calling thread : " << pthread_self() << endl;
if (fIsClosed > 0) {
*fStream << "!!! ERROR !!! : Accessing a client '" << fClientName << "' already closed " << "from " << function_name << endl;
*fStream << "!!! ERROR !!! : Accessing a client '" << fClientName << "' already closed " << "from " << function_name << endl;
*fStream << "This is likely to cause crash !'" << endl;
#ifdef __APPLE__
// Debugger();
#endif
#endif
}
}
pthread_t JackDebugClient::GetThreadID()
jack_native_thread_t JackDebugClient::GetThreadID()
{
CheckClient("GetThreadID");
return fClient->GetThreadID();
......@@ -428,7 +428,7 @@ void JackDebugClient::OnInfoShutdown(JackInfoShutdownCallback callback, void *ar
CheckClient("OnInfoShutdown");
fClient->OnInfoShutdown(callback, arg);
}
int JackDebugClient::TimeCallback(jack_nframes_t nframes, void *arg)
{
JackDebugClient* client = (JackDebugClient*)arg;
......
......@@ -7,12 +7,12 @@
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.
......@@ -25,7 +25,6 @@
#include <string.h>
#include <errno.h>
#include "JackCompilerDeps.h"
#include "types.h"
#ifdef __cplusplus
extern "C"
......@@ -44,17 +43,17 @@ extern "C"
EXPORT extern void (*jack_error_callback)(const char *desc);
EXPORT extern void (*jack_info_callback)(const char *desc);
EXPORT extern void default_jack_error_callback(const char *desc);
EXPORT extern void default_jack_info_callback(const char *desc);
EXPORT extern void silent_jack_error_callback(const char *desc);
EXPORT extern void silent_jack_info_callback(const char *desc);
typedef void (* jack_log_function_t)(int level, const char *message);
void jack_log_function(int level, const char *message);
EXPORT int set_threaded_log_function();
#ifdef __cplusplus
......
......@@ -21,7 +21,6 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
#ifndef __JackTime__
#define __JackTime__
#include "types.h"
#include "JackCompilerDeps.h"
#include "JackTypes.h"
......
......@@ -34,6 +34,12 @@ typedef signed long SInt32;
#include "JackTypes_os.h"
/**
* Type used to represent the value of free running
* monotonic clock with units of microseconds.
*/
typedef uint64_t jack_time_t;
typedef uint16_t jack_int_t; // Internal type for ports and refnum
typedef enum {
......
......@@ -522,6 +522,64 @@ int jack_set_xrun_callback (jack_client_t *,
/*@}*/
/**
* Tell the Jack server to call @a latency_callback whenever it
* is necessary to recompute the latencies for some or all
* Jack ports.
*
* @a latency_callback will be called twice each time it is
* needed, once being passed JackCaptureLatency and once
* JackPlaybackLatency. See @ref LatencyFunctions for
* the definition of each type of latency and related functions.
*
* <b>IMPORTANT: Most JACK clients do NOT need to register a latency
* callback.</b>
*
* Clients that meet any of the following conditions do NOT
* need to register a latency callback:
*
* - have only input ports
* - have only output ports
* - their output is totally unrelated to their input
* - their output is not delayed relative to their input
* (i.e. data that arrives in a given process()
* callback is processed and output again in the
* same callback)
*
* Clients NOT registering a latency callback MUST also
* satisfy this condition:
*
* - have no multiple distinct internal signal pathways
*
* This means that if your client has more than 1 input and
* output port, and considers them always "correlated"
* (e.g. as a stereo pair), then there is only 1 (e.g. stereo)
* signal pathway through the client. This would be true,
* for example, of a stereo FX rack client that has a
* left/right input pair and a left/right output pair.
*
* However, this is somewhat a matter of perspective. The
* same FX rack client could be connected so that its
* two input ports were connected to entirely separate
* sources. Under these conditions, the fact that the client
* does not register a latency callback MAY result
* in port latency values being incorrect.
*
* Clients that do not meet any of those conditions SHOULD
* register a latency callback.
*
* See the documentation for @ref jack_port_set_latency_range()
* on how the callback should operate. Remember that the @a mode
* argument given to the latency callback will need to be
* passed into @ref jack_port_set_latency_range()
*
* @return 0 on success, otherwise a non-zero error code
*/
int jack_set_latency_callback (jack_client_t *,
JackLatencyCallback latency_callback,
void *) JACK_WEAK_EXPORT;
/*@}*/
/**
* @defgroup ServerClientControl Controlling & querying JACK server operation
* @{
......@@ -784,66 +842,6 @@ int jack_port_tie (jack_port_t *src, jack_port_t *dst) JACK_OPTIONAL_WEAK_DEPREC
*/
int jack_port_untie (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
/**
* @return the time (in frames) between data being available or
* delivered at/to a port, and the time at which it arrived at or is
* delivered to the "other side" of the port. E.g. for a physical
* audio output port, this is the time between writing to the port and
* when the signal will leave the connector. For a physical audio
* input port, this is the time between the sound arriving at the
* connector and the corresponding frames being readable from the
* port.
*/
jack_nframes_t jack_port_get_latency (jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
/**
* The maximum of the sum of the latencies in every
* connection path that can be drawn between the port and other
* ports with the @ref JackPortIsTerminal flag set.
*/
jack_nframes_t jack_port_get_total_latency (jack_client_t *,
jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
/**
* The port latency is zero by default. Clients that control
* physical hardware with non-zero latency should call this
* to set the latency to its correct value. Note that the value
* should include any systemic latency present "outside" the
* physical hardware controlled by the client. For example,
* for a client controlling a digital audio interface connected
* to an external digital converter, the latency setting should
* include both buffering by the audio interface *and* the converter.
*/
void jack_port_set_latency (jack_port_t *, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT;
/**
* Request a complete recomputation of a port's total latency. This
* can be called by a client that has just changed the internal
* latency of its port using @function jack_port_set_latency
* and wants to ensure that all signal pathways in the graph
* are updated with respect to the values that will be returned
* by @function jack_port_get_total_latency.
*
* @return zero for successful execution of the request. non-zero
* otherwise.
*/
int jack_recompute_total_latency (jack_client_t*, jack_port_t* port) JACK_OPTIONAL_WEAK_EXPORT;
/**
* Request a complete recomputation of all port latencies. This
* can be called by a client that has just changed the internal
* latency of its port using @function jack_port_set_latency
* and wants to ensure that all signal pathways in the graph
* are updated with respect to the values that will be returned
* by @function jack_port_get_total_latency. It allows a client
* to change multiple port latencies without triggering a
* recompute for each change.
*
* @return zero for successful execution of the request. non-zero
* otherwise.
*/
int jack_recompute_total_latencies (jack_client_t*) JACK_OPTIONAL_WEAK_EXPORT;
/**
* Modify a port's short name. May be called at any time. If the
* resulting full name (including the @a "client_name:" prefix) is
......@@ -981,6 +979,224 @@ int jack_port_name_size(void) JACK_OPTIONAL_WEAK_EXPORT;
*/
int jack_port_type_size(void) JACK_OPTIONAL_WEAK_EXPORT;
/**
* @return the buffersize of a port of type @arg port_type.
*
* this function may only be called in a buffer_size callback.
*/
size_t jack_port_type_get_buffer_size (jack_client_t *client, const char *port_type) JACK_WEAK_EXPORT;
/*@}*/
/**
* @defgroup LatencyFunctions Managing and determining latency
*
* The purpose of JACK's latency API is to allow clients to
* easily answer two questions:
*
* - How long has it been since the data read from a port arrived
* at the edge of the JACK graph (either via a physical port
* or being synthesized from scratch)?
*
* - How long will it be before the data written to a port arrives
* at the edge of a JACK graph?
* To help answering these two questions, all JACK ports have two
* latency values associated with them, both measured in frames:
*
* <b>capture latency</b>: how long since the data read from
* the buffer of a port arrived at at
* a port marked with JackPortIsTerminal.
* The data will have come from the "outside
* world" if the terminal port is also
* marked with JackPortIsPhysical, or
* will have been synthesized by the client
* that owns the terminal port.
*
* <b>playback latency</b>: how long until the data
* written to the buffer of port will reach a port
* marked with JackPortIsTerminal.
*
* Both latencies might potentially have more than one value
* because there may be multiple pathways to/from a given port
* and a terminal port. Latency is therefore generally
* expressed a min/max pair.
*
* In most common setups, the minimum and maximum latency
* are the same, but this design accomodates more complex
* routing, and allows applications (and thus users) to
* detect cases where routing is creating an anomalous
* situation that may either need fixing or more
* sophisticated handling by clients that care about
* latency.
*
* See also @ref jack_set_latency_callback for details on how
* clients that add latency to the signal path should interact
* with JACK to ensure that the correct latency figures are
* used.
* @{
*/
/**
* The port latency is zero by default. Clients that control
* physical hardware with non-zero latency should call this
* to set the latency to its correct value. Note that the value
* should include any systemic latency present "outside" the
* physical hardware controlled by the client. For example,
* for a client controlling a digital audio interface connected
* to an external digital converter, the latency setting should
* include both buffering by the audio interface *and* the converter.
*
* @deprecated This method will be removed in the next major
* release of JACK. It should not be used in new code, and should
* be replaced by a latency callback that calls @ref
* jack_port_set_latency_range().
*/
void jack_port_set_latency (jack_port_t *, jack_nframes_t) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
/**
* return the latency range defined by @a mode for
* @a port, in frames.
*
* See @ref LatencyFunctions for the definition of each latency value.
*
* This is normally used in the LatencyCallback.
* and therefor safe to execute from callbacks.
*/
void jack_port_get_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT;
/**
* set the minimum and maximum latencies defined by
* @a mode for @a port, in frames.
*
* See @ref LatencyFunctions for the definition of each latency value.
*
* This function should ONLY be used inside a latency
* callback. The client should determine the current
* value of the latency using @ref jack_port_get_latency_range()
* (called using the same mode as @a mode)
* and then add some number of frames to that reflects
* latency added by the client.
*
* How much latency a client adds will vary
* dramatically. For most clients, the answer is zero
* and there is no reason for them to register a latency
* callback and thus they should never call this
* function.
*
* More complex clients that take an input signal,
* transform it in some way and output the result but
* not during the same process() callback will
* generally know a single constant value to add
* to the value returned by @ref jack_port_get_latency_range().
*
* Such clients would register a latency callback (see
* @ref jack_set_latency_callback) and must know what input
* ports feed which output ports as part of their
* internal state. Their latency callback will update
* the ports' latency values appropriately.
*
* A pseudo-code example will help. The @a mode argument to the latency
* callback will determine whether playback or capture
* latency is being set. The callback will use
* @ref jack_port_set_latency_range() as follows:
*
* \code
* jack_latency_range_t range;
* if (mode == JackPlaybackLatency) {
* foreach input_port in (all self-registered port) {
* jack_port_get_latency_range (port_feeding_input_port, JackPlaybackLatency, &range);
* range.min += min_delay_added_as_signal_flows_from port_feeding to input_port;
* range.max += max_delay_added_as_signal_flows_from port_feeding to input_port;
* jack_port_set_latency_range (input_port, JackPlaybackLatency, &range);
* }
* } else if (mode == JackCaptureLatency) {
* foreach output_port in (all self-registered port) {
* jack_port_get_latency_range (port_fed_by_output_port, JackCaptureLatency, &range);
* range.min += min_delay_added_as_signal_flows_from_output_port_to_fed_by_port;
* range.max += max_delay_added_as_signal_flows_from_output_port_to_fed_by_port;
* jack_port_set_latency_range (output_port, JackCaptureLatency, &range);
* }
* }
* \endcode
*
* In this relatively simple pseudo-code example, it is assumed that
* each input port or output is connected to only 1 output or input
* port respectively.
*
* If a port is connected to more than 1 other port, then the
* range.min and range.max values passed to @ref
* jack_port_set_latency_range() should reflect the minimum and
* maximum values across all connected ports.
*
* See the description of @ref jack_set_latency_callback for more
* information.
*/
void jack_port_set_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT;
/**
* Request a complete recomputation of all port latencies. This
* can be called by a client that has just changed the internal
* latency of its port using jack_port_set_latency
* and wants to ensure that all signal pathways in the graph
* are updated with respect to the values that will be returned
* by jack_port_get_total_latency. It allows a client
* to change multiple port latencies without triggering a
* recompute for each change.
*
* @return zero for successful execution of the request. non-zero
* otherwise.
*/
int jack_recompute_total_latencies (jack_client_t*) JACK_OPTIONAL_WEAK_EXPORT;
/**
* @return the time (in frames) between data being available or
* delivered at/to a port, and the time at which it arrived at or is
* delivered to the "other side" of the port. E.g. for a physical
* audio output port, this is the time between writing to the port and
* when the signal will leave the connector. For a physical audio
* input port, this is the time between the sound arriving at the
* connector and the corresponding frames being readable from the
* port.
*
* @deprecated This method will be removed in the next major
* release of JACK. It should not be used in new code, and should
* be replaced by jack_port_get_latency_range() in any existing
* use cases.
*/
jack_nframes_t jack_port_get_latency (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
/**
* The maximum of the sum of the latencies in every
* connection path that can be drawn between the port and other
* ports with the @ref JackPortIsTerminal flag set.
*
* @deprecated This method will be removed in the next major
* release of JACK. It should not be used in new code, and should
* be replaced by jack_port_get_latency_range() in any existing
* use cases.
*/
jack_nframes_t jack_port_get_total_latency (jack_client_t *,
jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
/**
* Request a complete recomputation of a port's total latency. This
* can be called by a client that has just changed the internal
* latency of its port using jack_port_set_latency
* and wants to ensure that all signal pathways in the graph
* are updated with respect to the values that will be returned
* by jack_port_get_total_latency.
*
* @return zero for successful execution of the request. non-zero
* otherwise.
*
* @deprecated This method will be removed in the next major
* release of JACK. It should not be used in new code, and should
* be replaced by jack_recompute_total_latencies() in any existing
* use cases.
*/
int jack_recompute_total_latency (jack_client_t*, jack_port_t* port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
/*@}*/
/**
......
/*
Copyright (C) 2002-2003 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
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
#include <stdlib.h>
#include <string.h>
#include <inttypes.h>
#include "timestamps.h"
#include "JackTime.h"
......@@ -60,7 +61,7 @@ jack_dump_timestamps (FILE *out)
unsigned long i;
for (i = 0; i < timestamp_index; ++i) {
fprintf (out, "%-.32s %" PRIu64 " %" PRIu64,
fprintf (out, "%-.32s %" PRIu64 " %" PRIu64,
timestamps[i].what, timestamps[i].when,
timestamps[i].when - timestamps[0].when);
if (i > 0) {
......
......@@ -13,7 +13,7 @@ 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
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
......@@ -24,7 +24,7 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
namespace Jack
{
int JackMachThread::SetThreadToPriority(pthread_t thread, UInt32 inPriority, Boolean inIsFixed, UInt64 period, UInt64 computation, UInt64 constraint)
int JackMachThread::SetThreadToPriority(jack_native_thread_t thread, UInt32 inPriority, Boolean inIsFixed, UInt64 period, UInt64 computation, UInt64 constraint)
{
if (inPriority == 96) {
// REAL-TIME / TIME-CONSTRAINT THREAD
......@@ -64,18 +64,18 @@ int JackMachThread::SetThreadToPriority(pthread_t thread, UInt32 inPriority, Boo
}
// returns the thread's priority as it was last set by the API
UInt32 JackMachThread::GetThreadSetPriority(pthread_t thread)
UInt32 JackMachThread::GetThreadSetPriority(jack_native_thread_t thread)
{
return GetThreadPriority(thread, THREAD_SET_PRIORITY);
}
// returns the thread's priority as it was last scheduled by the Kernel
UInt32 JackMachThread::GetThreadScheduledPriority(pthread_t thread)
UInt32 JackMachThread::GetThreadScheduledPriority(jack_native_thread_t thread)
{
return GetThreadPriority(thread, THREAD_SCHEDULED_PRIORITY);
}
UInt32 JackMachThread::GetThreadPriority(pthread_t thread, int inWhichPriority)
UInt32 JackMachThread::GetThreadPriority(jack_native_thread_t thread, int inWhichPriority)
{
thread_basic_info_data_t threadInfo;
policy_info_data_t thePolicyInfo;
......@@ -118,7 +118,7 @@ UInt32 JackMachThread::GetThreadPriority(pthread_t thread, int inWhichPriority)
return 0;
}
int JackMachThread::GetParams(pthread_t thread, UInt64* period, UInt64* computation, UInt64* constraint)
int JackMachThread::GetParams(jack_native_thread_t thread, UInt64* period, UInt64* computation, UInt64* constraint)
{
thread_time_constraint_policy_data_t theTCPolicy;
mach_msg_type_number_t count = THREAD_TIME_CONSTRAINT_POLICY_COUNT;
......@@ -144,11 +144,11 @@ int JackMachThread::Kill()
{
// pthread_cancel still not yet implemented in Darwin (TO CHECK ON TIGER)
jack_log("JackMachThread::Kill");
if (fThread != (pthread_t)NULL) { // If thread has been started
if (fThread != (jack_native_thread_t)NULL) { // If thread has been started
mach_port_t machThread = pthread_mach_thread_np(fThread);
int res = (thread_terminate(machThread) == KERN_SUCCESS) ? 0 : -1;
fThread = (pthread_t)NULL;
fThread = (jack_native_thread_t)NULL;
return res;
} else {
return -1;
......@@ -159,7 +159,7 @@ int JackMachThread::AcquireRealTime()
{
jack_log("JackMachThread::AcquireRealTime fPeriod = %ld fComputation = %ld fConstraint = %ld",
long(fPeriod / 1000), long(fComputation / 1000), long(fConstraint / 1000));
return (fThread != (pthread_t)NULL) ? AcquireRealTimeImp(fThread, fPeriod, fComputation, fConstraint) : -1;
return (fThread != (jack_native_thread_t)NULL) ? AcquireRealTimeImp(fThread, fPeriod, fComputation, fConstraint) : -1;
}
int JackMachThread::AcquireSelfRealTime()
......@@ -181,7 +181,7 @@ int JackMachThread::AcquireSelfRealTime(int priority)
return AcquireSelfRealTime();
}
int JackMachThread::AcquireRealTimeImp(pthread_t thread, UInt64 period, UInt64 computation, UInt64 constraint)
int JackMachThread::AcquireRealTimeImp(jack_native_thread_t thread, UInt64 period, UInt64 computation, UInt64 constraint)
{
SetThreadToPriority(thread, 96, true, period, computation, constraint);
return 0;
......@@ -189,7 +189,7 @@ int JackMachThread::AcquireRealTimeImp(pthread_t thread, UInt64 period, UInt64 c
int JackMachThread::DropRealTime()
{
return (fThread != (pthread_t)NULL) ? DropRealTimeImp(fThread) : -1;
return (fThread != (jack_native_thread_t)NULL) ? DropRealTimeImp(fThread) : -1;
}
int JackMachThread::DropSelfRealTime()
......@@ -197,7 +197,7 @@ int JackMachThread::DropSelfRealTime()
return DropRealTimeImp(pthread_self());
}
int JackMachThread::DropRealTimeImp(pthread_t thread)
int JackMachThread::DropRealTimeImp(jack_native_thread_t thread)
{
SetThreadToPriority(thread, 63, false, 0, 0, 0);
return 0;
......
......@@ -13,7 +13,7 @@ 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
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
......@@ -87,9 +87,9 @@ class SERVER_EXPORT JackMachThread : public JackPosixThread
UInt64 fComputation;
UInt64 fConstraint;
static UInt32 GetThreadSetPriority(pthread_t thread);
static UInt32 GetThreadScheduledPriority(pthread_t thread);
static UInt32 GetThreadPriority(pthread_t thread, int inWhichPriority);
static UInt32 GetThreadSetPriority(jack_native_thread_t thread);
static UInt32 GetThreadScheduledPriority(jack_native_thread_t thread);
static UInt32 GetThreadPriority(jack_native_thread_t thread, int inWhichPriority);
public:
......@@ -105,23 +105,23 @@ class SERVER_EXPORT JackMachThread : public JackPosixThread
int AcquireRealTime(); // Used when called from another thread
int AcquireSelfRealTime(); // Used when called from thread itself
int AcquireRealTime(int priority); // Used when called from another thread
int AcquireSelfRealTime(int priority); // Used when called from thread itself
int DropRealTime(); // Used when called from another thread
int DropSelfRealTime(); // Used when called from thread itself
void SetParams(UInt64 period, UInt64 computation, UInt64 constraint);
static int GetParams(pthread_t thread, UInt64* period, UInt64* computation, UInt64* constraint);