From 25ef5032c77e5c774587fafaf66ab5e30bfd40d0 Mon Sep 17 00:00:00 2001 From: paul Date: Mon, 28 Feb 2011 20:50:58 +0000 Subject: [PATCH] weak linkage docs, take 1 git-svn-id: svn+ssh://jackaudio.org/trunk/jack@4132 0c269be4-1314-0410-8aa9-9f06e86f4224 --- doc/Makefile.am | 3 ++- doc/mainpage.dox | 1 + doc/reference.doxygen.in | 3 ++- jack/weakjack.h | 49 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 54 insertions(+), 2 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index 5e5767e..656f19a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,8 @@ DOXSOURCES=mainpage.dox transport.dox porting.dox fsm.png fsm.eps \ ../jack/transport.h \ ../jack/types.h \ ../jack/midiport.h \ - ../jack/session.h + ../jack/session.h \ + ../jack/weakjack.h EXTRA_DIST=mainpage.dox transport.dox fsm.png fsm.eps porting.dox diff --git a/doc/mainpage.dox b/doc/mainpage.dox index e76439e..4542e67 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -97,6 +97,7 @@ little clearer: - @ref NonCallbackAPI - @ref MIDIAPI - @ref SessionClientFunctions + - @ref WeakLinkage The full API is described in: diff --git a/doc/reference.doxygen.in b/doc/reference.doxygen.in index bc85355..33d5fe0 100644 --- a/doc/reference.doxygen.in +++ b/doc/reference.doxygen.in @@ -526,7 +526,8 @@ INPUT = @top_srcdir@/doc/mainpage.dox \ @top_srcdir@/jack/transport.h \ @top_srcdir@/jack/types.h \ @top_srcdir@/jack/midiport.h \ - @top_srcdir@/jack/session.h + @top_srcdir@/jack/session.h \ + @top_srcdir@/jack/weakjack.h \ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/jack/weakjack.h b/jack/weakjack.h index 11d2aca..c636690 100644 --- a/jack/weakjack.h +++ b/jack/weakjack.h @@ -20,6 +20,53 @@ #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. + * + * 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 before any other JACK header. + * This will make the 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. + * + * + */ + #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 @@ -49,4 +96,6 @@ #endif #endif +x1/*@}*/ + #endif /* weakjack */