126 lines
5.2 KiB
C
126 lines
5.2 KiB
C
/*
|
|
Copyright (C) 2010 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 __weakjack_h__
|
|
#define __weakjack_h__
|
|
|
|
/**
|
|
* @defgroup WeakLinkage Managing support for newer/older versions of JACK
|
|
* @{ One challenge faced by developers is that of taking
|
|
* advantage of new features introduced in new versions
|
|
* of [ JACK ] while still supporting older versions of
|
|
* the system. Normally, if an application uses a new
|
|
* feature in a library/API, it is unable to run on
|
|
* earlier versions of the library/API that do not
|
|
* support that feature. Such applications would either
|
|
* fail to launch or crash when an attempt to use the
|
|
* feature was made. This problem cane be solved using
|
|
* weakly-linked symbols.
|
|
*
|
|
* When a symbol in a framework is defined as weakly
|
|
* linked, the symbol does not have to be present at
|
|
* runtime for a process to continue running. The static
|
|
* linker identifies a weakly linked symbol as such in
|
|
* any code module that references the symbol. The
|
|
* dynamic linker uses this same information at runtime
|
|
* to determine whether a process can continue
|
|
* running. If a weakly linked symbol is not present in
|
|
* the framework, the code module can continue to run as
|
|
* long as it does not reference the symbol. However, if
|
|
* the symbol is present, the code can use it normally.
|
|
*
|
|
* (adapted from: http://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html)
|
|
*
|
|
* A concrete example will help. Suppose that someone uses a version
|
|
* of a JACK client we'll call "Jill". Jill was linked against a version
|
|
* of JACK that contains a newer part of the API (say, jack_set_latency_callback())
|
|
* and would like to use it if it is available.
|
|
*
|
|
* When Jill is run on a system that has a suitably "new" version of
|
|
* JACK, this function will be available entirely normally. But if Jill
|
|
* is run on a system with an old version of JACK, the function isn't
|
|
* available.
|
|
*
|
|
* With normal symbol linkage, this would create a startup error whenever
|
|
* someone tries to run Jill with the "old" version of JACK. However, functions
|
|
* added to JACK after version 0.116.2 are all declared to have "weak" linkage
|
|
* which means that their absence doesn't cause an error during program
|
|
* startup. Instead, Jill can test whether or not the symbol jack_set_latency_callback
|
|
* is null or not. If its null, it means that the JACK installed on this machine
|
|
* is too old to support this function. If its not null, then Jill can use it
|
|
* just like any other function in the API. For example:
|
|
*
|
|
* \code
|
|
* if (jack_set_latency_callback) {
|
|
* jack_set_latency_callback (jill_client, jill_latency_callback, arg);
|
|
* }
|
|
* \endcode
|
|
*
|
|
* However, there are clients that may want to use this approach to parts of the
|
|
* the JACK API that predate 0.116.2. For example, they might want to see if even
|
|
* really old basic parts of the API like jack_client_open() exist at runtime.
|
|
*
|
|
* Such clients should include <jack/weakjack.h> before any other JACK header.
|
|
* This will make the \b entire JACK API be subject to weak linkage, so that any
|
|
* and all functions can be checked for existence at runtime. It is important
|
|
* to understand that very few clients need to do this - if you use this
|
|
* feature you should have a clear reason to do so.
|
|
*
|
|
*
|
|
*/
|
|
|
|
#ifdef __APPLE__
|
|
#define WEAK_ATTRIBUTE weak_import
|
|
#else
|
|
#define WEAK_ATTRIBUTE __weak__
|
|
#endif
|
|
|
|
#ifndef JACK_OPTIONAL_WEAK_EXPORT
|
|
/* JACK_OPTIONAL_WEAK_EXPORT needs to be a macro which
|
|
expands into a compiler directive. If non-null, the directive
|
|
must tell the compiler to arrange for weak linkage of
|
|
the symbol it used with. For this to work fully may
|
|
require linker arguments for the client as well.
|
|
*/
|
|
#ifdef __GNUC__
|
|
#define JACK_OPTIONAL_WEAK_EXPORT __attribute__((WEAK_ATTRIBUTE))
|
|
#else
|
|
/* Add other things here for non-gcc platforms */
|
|
#endif
|
|
#endif
|
|
|
|
#ifndef JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
|
|
/* JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT needs to be a macro
|
|
which expands into a compiler directive. If non-null, the directive
|
|
must tell the compiler to arrange for weak linkage of the
|
|
symbol it is used with AND optionally to mark the symbol
|
|
as deprecated. For this to work fully may require
|
|
linker arguments for the client as well.
|
|
*/
|
|
#ifdef __GNUC__
|
|
#define JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT __attribute__((WEAK_ATTRIBUTE,__deprecated__))
|
|
#else
|
|
/* Add other things here for non-gcc platforms */
|
|
#endif
|
|
#endif
|
|
|
|
/**@}*/
|
|
|
|
#endif /* weakjack */
|