/
weakjack.h
125 lines (114 loc) · 5.27 KB
/
weakjack.h
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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
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
117
118
119
120
121
122
123
124
125
/*
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 abscence 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 */