common/jack/weakjack.h

   1 /*
   2     Copyright (C) 2010 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 __weakjack_h__
  21 #define __weakjack_h__
  22
  23 /**
  24  * @defgroup WeakLinkage Managing support for newer/older versions of JACK
  25  * @{ One challenge faced by developers is that of taking
  26  *    advantage of new features introduced in new versions
  27  *    of [ JACK ] while still supporting older versions of
  28  *    the system. Normally, if an application uses a new
  29  *    feature in a library/API, it is unable to run on
  30  *    earlier versions of the library/API that do not
  31  *    support that feature. Such applications would either
  32  *    fail to launch or crash when an attempt to use the
  33  *    feature was made. This problem cane be solved using
  34  *    weakly-linked symbols.
  35  *
  36  *    When a symbol in a framework is defined as weakly
  37  *    linked, the symbol does not have to be present at
  38  *    runtime for a process to continue running. The static
  39  *    linker identifies a weakly linked symbol as such in
  40  *    any code module that references the symbol. The
  41  *    dynamic linker uses this same information at runtime
  42  *    to determine whether a process can continue
  43  *    running. If a weakly linked symbol is not present in
  44  *    the framework, the code module can continue to run as
  45  *    long as it does not reference the symbol. However, if
  46  *    the symbol is present, the code can use it normally.
  47  *
  48  *        (adapted from: http://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html)
  49  *
  50  *    A concrete example will help. Suppose that someone uses a version
  51  *    of a JACK client we'll call "Jill". Jill was linked against a version
  52  *    of JACK that contains a newer part of the API (say, jack_set_latency_callback())
  53  *    and would like to use it if it is available.
  54  *
  55  *    When Jill is run on a system that has a suitably "new" version of
  56  *    JACK, this function will be available entirely normally. But if Jill
  57  *    is run on a system with an old version of JACK, the function isn't
  58  *    available.
  59  *
  60  *    With normal symbol linkage, this would create a startup error whenever
  61  *    someone tries to run Jill with the "old" version of JACK. However, functions
  62  *    added to JACK after version 0.116.2 are all declared to have "weak" linkage
  63  *    which means that their absence doesn't cause an error during program
  64  *    startup. Instead, Jill can test whether or not the symbol jack_set_latency_callback
  65  *    is null or not. If its null, it means that the JACK installed on this machine
  66  *    is too old to support this function. If its not null, then Jill can use it
  67  *    just like any other function in the API. For example:
  68  *
  69  * \code
  70  * if (jack_set_latency_callback) {
  71  *       jack_set_latency_callback (jill_client, jill_latency_callback, arg);
  72  * }
  73  * \endcode
  74  *
  75  *    However, there are clients that may want to use this approach to parts of the
  76  *    the JACK API that predate 0.116.2. For example, they might want to see if even
  77  *    really old basic parts of the API like jack_client_open() exist at runtime.
  78  *
  79  *    Such clients should include <jack/weakjack.h> before any other JACK header.
  80  *    This will make the \b entire JACK API be subject to weak linkage, so that any
  81  *    and all functions can be checked for existence at runtime. It is important
  82  *    to understand that very few clients need to do this - if you use this
  83  *    feature you should have a clear reason to do so.
  84  *
  85  *
  86  */
  87
  88 #ifdef __APPLE__
  89 #define WEAK_ATTRIBUTE weak_import
  90 #else
  91 #define WEAK_ATTRIBUTE __weak__
  92 #endif
  93
  94 #ifndef JACK_OPTIONAL_WEAK_EXPORT
  95 /* JACK_OPTIONAL_WEAK_EXPORT needs to be a macro which
  96    expands into a compiler directive. If non-null, the directive
  97    must tell the compiler to arrange for weak linkage of
  98    the symbol it used with. For this to work fully may
  99    require linker arguments for the client as well.
 100 */
 101 #ifdef __GNUC__
 102 #define JACK_OPTIONAL_WEAK_EXPORT __attribute__((WEAK_ATTRIBUTE))
 103 #else
 104 /* Add other things here for non-gcc platforms */
 105 #endif
 106 #endif
 107
 108 #ifndef JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
 109 /* JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT needs to be a macro
 110    which expands into a compiler directive. If non-null, the directive
 111    must tell the compiler to arrange for weak linkage of the
 112    symbol it is used with AND optionally to mark the symbol
 113    as deprecated. For this to work fully may require
 114    linker arguments for the client as well.
 115 */
 116 #ifdef __GNUC__
 117 #define JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT __attribute__((WEAK_ATTRIBUTE,__deprecated__))
 118 #else
 119 /* Add other things here for non-gcc platforms */
 120 #endif
 121 #endif
 122
 123 /*@}*/
 124
 125 #endif /* weakjack */