All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
attributes.h
Go to the documentation of this file.
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_BASE_ARCH_ATTRIBUTES_H
8#define PXR_BASE_ARCH_ATTRIBUTES_H
9
15
16#include "pxr/pxr.h"
18
19PXR_NAMESPACE_OPEN_SCOPE
20
21#if defined(doxygen)
22
34# define ARCH_PRINTF_FUNCTION(_fmt, _firstArg)
35
48# define ARCH_SCANF_FUNCTION(_fmt, _firstArg)
49
58# define ARCH_NOINLINE
59
72# define ARCH_UNUSED_ARG
73
87# define ARCH_UNUSED_FUNCTION
88
107# define ARCH_USED_FUNCTION
108
126# define ARCH_CONSTRUCTOR(_name, _priority, ...)
127
145# define ARCH_DESTRUCTOR(_name, _priority, ...)
146
153# define ARCH_EMPTY_BASES
154
155#elif defined(ARCH_COMPILER_GCC) || defined(ARCH_COMPILER_CLANG)
156
157# define ARCH_PRINTF_FUNCTION(_fmt, _firstArg) \
158 __attribute__((format(printf, _fmt, _firstArg)))
159# define ARCH_SCANF_FUNCTION(_fmt, _firstArg) \
160 __attribute__((format(scanf, _fmt, _firstArg)))
161# define ARCH_NOINLINE __attribute__((noinline))
162# define ARCH_UNUSED_ARG __attribute__ ((unused))
163# define ARCH_UNUSED_FUNCTION __attribute__((unused))
164# define ARCH_USED_FUNCTION __attribute__((used))
165# define ARCH_EMPTY_BASES
166
167#elif defined(ARCH_COMPILER_MSVC)
168
169# define ARCH_PRINTF_FUNCTION(_fmt, _firstArg)
170# define ARCH_SCANF_FUNCTION(_fmt, _firstArg)
171# define ARCH_NOINLINE // __declspec(noinline)
172# define ARCH_UNUSED_ARG
173# define ARCH_UNUSED_FUNCTION
174# define ARCH_USED_FUNCTION
175# define ARCH_EMPTY_BASES __declspec(empty_bases)
176
177#else
178
179// Leave macros undefined so we'll fail to build on a new system/compiler
180// rather than fail mysteriously at runtime.
181
182#endif
183
184// Helper to do on-demand static initialziation. We need to insert per-library
185// static initializers if the ARCH_CONSTRUCTOR macros are used, etc, but we
186// don't want that to happen otherwise. This mechanism makes that possible. It
187// works by creating a class template (Arch_PerLibInit) that has hidden
188// visibility and a static member of its template parameter (StaticInit). In
189// its constructor, it "uses" its static member 'init', in order to ensure it
190// gets instantiated. Since it's a static member, it gets initialized only if
191// it's instantiated. This lets us have macros like ARCH_CONSTRUCTOR() that
192// require a static initializer, but to only emit that static initializer in
193// translation units that actually invoke the macro. Clients typically do this
194// by way of the _ARCH_ENSURE_PER_LIB_INIT macro. This is tested on all current
195// supported compilers (clang, gcc, msvc). The hidden visibility is required to
196// ensure that each library gets its own initialization. Without it, on Linux,
197// there would be exactly *one* initialization no matter how many libraries are
198// loaded.
199template <class StaticInit>
200struct ARCH_HIDDEN Arch_PerLibInit {
201 Arch_PerLibInit() { /* "use" of init here forces instantiation */
202 (void)init; }
203private:
204 static StaticInit init;
205};
206template <class StaticInit>
207StaticInit Arch_PerLibInit<StaticInit>::init;
208
209#define _ARCH_CAT_NOEXPAND(a, b) a ## b
210#define _ARCH_CAT(a, b) _ARCH_CAT_NOEXPAND(a, b)
211#define _ARCH_ENSURE_PER_LIB_INIT(T, prefix) \
212 static Arch_PerLibInit<T> _ARCH_CAT(prefix, __COUNTER__)
213
214#if defined(doxygen)
215
216// The macros are already defined above in doxygen.
217
218#elif defined(ARCH_OS_DARWIN)
219
220// Entry for a constructor/destructor in the custom section.
221struct Arch_ConstructorEntry {
222 typedef void (*Type)(void);
223 Type function;
224 unsigned int version:24; // USD version
225 unsigned int priority:8; // Priority of function
226};
227
228// Emit a Arch_ConstructorEntry in the __Data,pxrctor section.
229# define ARCH_CONSTRUCTOR(_name, _priority, ...) \
230 static void _name(__VA_ARGS__); \
231 static const Arch_ConstructorEntry _ARCH_CAT_NOEXPAND(arch_ctor_, _name) \
232 __attribute__((used, section("__DATA,pxrctor"))) = { \
233 reinterpret_cast<Arch_ConstructorEntry::Type>(&_name), \
234 static_cast<unsigned>(PXR_VERSION), \
235 _priority \
236 }; \
237 static void _name(__VA_ARGS__)
238
239// Emit a Arch_ConstructorEntry in the __Data,pxrdtor section.
240# define ARCH_DESTRUCTOR(_name, _priority, ...) \
241 static void _name(__VA_ARGS__); \
242 static const Arch_ConstructorEntry _ARCH_CAT_NOEXPAND(arch_dtor_, _name) \
243 __attribute__((used, section("__DATA,pxrdtor"))) = { \
244 reinterpret_cast<Arch_ConstructorEntry::Type>(&_name), \
245 static_cast<unsigned>(PXR_VERSION), \
246 _priority \
247 }; \
248 static void _name(__VA_ARGS__)
249
250#elif defined(ARCH_COMPILER_GCC) || defined(ARCH_COMPILER_CLANG)
251
252// The used attribute is required to prevent these apparently unused functions
253// from being removed by the linker.
254# define ARCH_CONSTRUCTOR(_name, _priority, ...) \
255 __attribute__((used, section(".pxrctor"), constructor((_priority) + 100))) \
256 static void _name(__VA_ARGS__)
257# define ARCH_DESTRUCTOR(_name, _priority, ...) \
258 __attribute__((used, section(".pxrdtor"), destructor((_priority) + 100))) \
259 static void _name(__VA_ARGS__)
260
261#elif defined(ARCH_OS_WINDOWS)
262
263# include "pxr/base/arch/api.h"
264
265// Entry for a constructor/destructor in the custom section.
266 __declspec(align(16))
267 struct Arch_ConstructorEntry {
268 typedef void (__cdecl *Type)(void);
269 Type function;
270 unsigned int version:24; // USD version
271 unsigned int priority:8; // Priority of function
272 };
273
274// Declare the special sections.
275# pragma section(".pxrctor", read)
276# pragma section(".pxrdtor", read)
277
278// Objects of this type run the ARCH_CONSTRUCTOR and ARCH_DESTRUCTOR functions
279// for the library containing the object in the c'tor and d'tor, respectively.
280// Each HMODULE is handled at most once.
281struct Arch_ConstructorInit {
282 ARCH_API Arch_ConstructorInit();
283 ARCH_API ~Arch_ConstructorInit();
284};
285
286// Emit a Arch_ConstructorEntry in the .pxrctor section. The namespace and
287// extern are to convince the compiler and linker to leave the object in the
288// final library/executable instead of stripping it out. In clang/gcc we use
289// __attribute__((used)) to do that.
290# define ARCH_CONSTRUCTOR(_name, _priority, ...) \
291 static void _name(__VA_ARGS__); \
292 namespace { \
293 __declspec(allocate(".pxrctor")) \
294 extern const Arch_ConstructorEntry \
295 _ARCH_CAT_NOEXPAND(arch_ctor_, _name) = { \
296 reinterpret_cast<Arch_ConstructorEntry::Type>(&_name), \
297 static_cast<unsigned>(PXR_VERSION), \
298 _priority \
299 }; \
300 } \
301 _ARCH_ENSURE_PER_LIB_INIT(Arch_ConstructorInit, _archCtorInit); \
302 static void _name(__VA_ARGS__)
303
304 // Emit a Arch_ConstructorEntry in the .pxrdtor section.
305# define ARCH_DESTRUCTOR(_name, _priority, ...) \
306 static void _name(__VA_ARGS__); \
307 namespace { \
308 __declspec(allocate(".pxrdtor")) \
309 extern const Arch_ConstructorEntry \
310 _ARCH_CAT_NOEXPAND(arch_dtor_, _name) = { \
311 reinterpret_cast<Arch_ConstructorEntry::Type>(&_name), \
312 static_cast<unsigned>(PXR_VERSION), \
313 _priority \
314 }; \
315 } \
316 _ARCH_ENSURE_PER_LIB_INIT(Arch_ConstructorInit, _archCtorInit); \
317 static void _name(__VA_ARGS__)
318
319#else
320
321// Leave macros undefined so we'll fail to build on a new system/compiler
322// rather than fail mysteriously at runtime.
323
324#endif
325
326PXR_NAMESPACE_CLOSE_SCOPE
327
328#endif // PXR_BASE_ARCH_ATTRIBUTES_H
Defines symbol visibility macros.