attributes.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_BASE_ARCH_ATTRIBUTES_H
#define PXR_BASE_ARCH_ATTRIBUTES_H
 
 
#include "pxr/pxr.h"
#include "pxr/base/arch/export.h"
 
PXR_NAMESPACE_OPEN_SCOPE
 
#if defined(doxygen)
 
#   define ARCH_PRINTF_FUNCTION(_fmt, _firstArg)
 
#   define ARCH_SCANF_FUNCTION(_fmt, _firstArg)
 
#   define ARCH_NOINLINE
 
#   define ARCH_UNUSED_ARG
 
#   define ARCH_UNUSED_FUNCTION
 
#   define ARCH_USED_FUNCTION
 
#   define ARCH_CONSTRUCTOR(_name, _priority)
 
#   define ARCH_DESTRUCTOR(_name, _priority)
 
#   define ARCH_EMPTY_BASES
 
#elif defined(ARCH_COMPILER_GCC) || defined(ARCH_COMPILER_CLANG)
 
#   define ARCH_PRINTF_FUNCTION(_fmt, _firstArg) \
        __attribute__((format(printf, _fmt, _firstArg)))
#   define ARCH_SCANF_FUNCTION(_fmt, _firstArg) \
        __attribute__((format(scanf, _fmt, _firstArg)))
#   define ARCH_NOINLINE __attribute__((noinline))
#   define ARCH_ALWAYS_INLINE __attribute__((always_inline))
#   define ARCH_UNUSED_ARG   __attribute__ ((unused))
#   define ARCH_UNUSED_FUNCTION __attribute__((unused))
#   define ARCH_USED_FUNCTION __attribute__((used))
#   define ARCH_EMPTY_BASES
 
#elif defined(ARCH_COMPILER_MSVC)
 
#   define ARCH_PRINTF_FUNCTION(_fmt, _firstArg)
#   define ARCH_SCANF_FUNCTION(_fmt, _firstArg)
#   define ARCH_NOINLINE // __declspec(noinline)
#   define ARCH_ALWAYS_INLINE
#   define ARCH_UNUSED_ARG
#   define ARCH_UNUSED_FUNCTION
#   define ARCH_USED_FUNCTION
#   define ARCH_EMPTY_BASES __declspec(empty_bases)
 
#else
 
// Leave macros undefined so we'll fail to build on a new system/compiler
// rather than fail mysteriously at runtime.
 
#endif
 
// Helper to do on-demand static initialization.  We need to insert per-library
// static initializers if the ARCH_CONSTRUCTOR macros are used, etc, but we
// don't want that to happen otherwise.  This mechanism makes that possible.  It
// works by creating a class template (Arch_PerLibInit) that has hidden
// visibility and a static member of its template parameter (StaticInit).  In
// its constructor, it "uses" its static member 'init', in order to ensure it
// gets instantiated.  Since it's a static member, it gets initialized only if
// it's instantiated.  This lets us have macros like ARCH_CONSTRUCTOR() that
// require a static initializer, but to only emit that static initializer in
// translation units that actually invoke the macro.  Clients typically do this
// by way of the _ARCH_ENSURE_PER_LIB_INIT macro.  This is tested on all current
// supported compilers (clang, gcc, msvc).  The hidden visibility is required to
// ensure that each library gets its own initialization.  Without it, on Linux,
// there would be exactly *one* initialization no matter how many libraries are
// loaded.
template <class StaticInit>
struct ARCH_HIDDEN Arch_PerLibInit {
    Arch_PerLibInit() { /* "use" of init here forces instantiation */
        (void)init; }
private:
    static StaticInit init;
};
template <class StaticInit>
StaticInit Arch_PerLibInit<StaticInit>::init;
 
#define _ARCH_CAT_NOEXPAND(a, b) a ## b
#define _ARCH_CAT(a, b) _ARCH_CAT_NOEXPAND(a, b)
#define _ARCH_ENSURE_PER_LIB_INIT(T, prefix) \
    static Arch_PerLibInit<T> _ARCH_CAT(prefix, __COUNTER__)
 
#if defined(doxygen)
 
// The macros are already defined above in doxygen.
 
#elif defined(ARCH_OS_DARWIN)
 
// Entry for a constructor/destructor in the custom section.
struct Arch_ConstructorEntry {
    typedef void (*Type)(void);
    Type function;
    unsigned int version:24;    // USD version
    unsigned int priority:8;    // Priority of function
};
 
// Emit a Arch_ConstructorEntry in the __Data,pxrctor section.
#   define ARCH_CONSTRUCTOR(_name, _priority)                                  \
    static void _name();                                                       \
    static const Arch_ConstructorEntry _ARCH_CAT_NOEXPAND(arch_ctor_, _name)   \
        __attribute__((used, section("__DATA,pxrctor"))) = {                   \
        reinterpret_cast<Arch_ConstructorEntry::Type>(&_name),                 \
        static_cast<unsigned>(PXR_VERSION),                                    \
        _priority                                                              \
    };                                                                         \
    static void _name()
    
// Emit a Arch_ConstructorEntry in the __Data,pxrdtor section.
#   define ARCH_DESTRUCTOR(_name, _priority)                                   \
    static void _name();                                                       \
    static const Arch_ConstructorEntry _ARCH_CAT_NOEXPAND(arch_dtor_, _name)   \
        __attribute__((used, section("__DATA,pxrdtor"))) = {                   \
        reinterpret_cast<Arch_ConstructorEntry::Type>(&_name),                 \
        static_cast<unsigned>(PXR_VERSION),                                    \
        _priority                                                              \
    };                                                                         \
    static void _name()
 
#elif defined(ARCH_COMPILER_GCC) || defined(ARCH_COMPILER_CLANG)
 
// The used attribute is required to prevent these apparently unused functions
// from being removed by the linker.
#   define ARCH_CONSTRUCTOR(_name, _priority) \
        __attribute__((used, section(".pxrctor"), constructor((_priority) + 100))) \
        static void _name()
#   define ARCH_DESTRUCTOR(_name, _priority) \
        __attribute__((used, section(".pxrdtor"), destructor((_priority) + 100))) \
        static void _name()
 
#elif defined(ARCH_OS_WINDOWS)
    
#    include "pxr/base/arch/api.h"
    
// Entry for a constructor/destructor in the custom section.
    __declspec(align(16))
    struct Arch_ConstructorEntry {
        typedef void (__cdecl *Type)(void);
        Type function;
        unsigned int version:24;    // USD version
        unsigned int priority:8;    // Priority of function
    };
 
// Declare the special sections.
#   pragma section(".pxrctor", read)
#   pragma section(".pxrdtor", read)
 
// Objects of this type run the ARCH_CONSTRUCTOR and ARCH_DESTRUCTOR functions
// for the library containing the object in the c'tor and d'tor, respectively.
// Each HMODULE is handled at most once.
struct Arch_ConstructorInit {
    ARCH_API Arch_ConstructorInit();
    ARCH_API ~Arch_ConstructorInit();
};
 
// Emit a Arch_ConstructorEntry in the .pxrctor section.  The namespace and
// extern are to convince the compiler and linker to leave the object in the
// final library/executable instead of stripping it out.  In clang/gcc we use
// __attribute__((used)) to do that.
#   define ARCH_CONSTRUCTOR(_name, _priority)                                  \
    static void _name();                                                       \
    namespace {                                                                \
    __declspec(allocate(".pxrctor"))                                           \
    extern const Arch_ConstructorEntry                                         \
    _ARCH_CAT_NOEXPAND(arch_ctor_, _name) = {                                  \
        reinterpret_cast<Arch_ConstructorEntry::Type>(&_name),                 \
        static_cast<unsigned>(PXR_VERSION),                                    \
        _priority                                                              \
    };                                                                         \
    }                                                                          \
    _ARCH_ENSURE_PER_LIB_INIT(Arch_ConstructorInit, _archCtorInit);            \
    static void _name()
 
    // Emit a Arch_ConstructorEntry in the .pxrdtor section.
#   define ARCH_DESTRUCTOR(_name, _priority)                                   \
    static void _name();                                                       \
    namespace {                                                                \
    __declspec(allocate(".pxrdtor"))                                           \
    extern const Arch_ConstructorEntry                                         \
    _ARCH_CAT_NOEXPAND(arch_dtor_, _name) = {                                  \
        reinterpret_cast<Arch_ConstructorEntry::Type>(&_name),                 \
        static_cast<unsigned>(PXR_VERSION),                                    \
        _priority                                                              \
    };                                                                         \
    }                                                                          \
    _ARCH_ENSURE_PER_LIB_INIT(Arch_ConstructorInit, _archCtorInit);            \
    static void _name()
 
#else
 
// Leave macros undefined so we'll fail to build on a new system/compiler
// rather than fail mysteriously at runtime.
 
#endif
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_BASE_ARCH_ATTRIBUTES_H