stlab.adobe.com Adobe Systems Incorporated

Thread safety code for compilation in environments both with and without thread support. More...

Defines

#define ADOBE_GLOBAL_MUTEX_DEFINITION(signature)
#define ADOBE_GLOBAL_MUTEX_INSTANCE(signature)
#define ADOBE_ONCE_DECLARATION(signature)
#define ADOBE_ONCE_DEFINITION(signature, func)
#define ADOBE_ONCE_INIT
#define ADOBE_ONCE_INSTANCE(signature)
#define ADOBE_ONCE_STATIC_INSTANCE(signature)

Typedefs

typedef bool once_flag

Functions

void call_once (void(*func)(), adobe::once_flag &flag)

Detailed Description

The adobe/once collection provides threadsafe functionality for code that can be built in environments that are either thread-aware or have no thread support. The code automatically detects the environment in which it is being built, and compiles the proper code for that environment. In a thread-aware environment the code utilizes the boost thread codebase, while in a environments without thread support it uses booleans. Thread support is determined by BOOST_HAS_THREADS and can be explicitly disabled by defining BOOST_DISABLE_THREADS.

ADOBE_ONCE Macro Documentation

The ADOBE_ONCE suite of macros is intended to provide boilerplate code that is common in thread-aware environments to support thread safety for intialization of translation unit globals, static variables, and shared variables across multiple translation units. The macros, like the rest of the adobe/once suite, can be used in environments without thread support environments to achieve similar one-time execution guarantees the thread-aware environment leverages.
The signature parameter in all of these macros ties multiple macros together and provides for a distinguishing tag that prevents multiple ADOBE_ONCE instance collisions. This tag will be appended to utility structs and variables within the macro, so is not a string: just a tag.

There are three (four) cases for which the ADOBE_ONCE macros are written:

1a) ADOBE_ONCE_DECLARATION/STATIC_INSTANCE/DEFINITION (Globally Shared)
Used to initialize items before first function call in the compilation unit (static initialization). These should be used sparingly as most compilers will initialize prior to main, which may add to launch times. Items initialized this way can be used by other objects at static initialization time which are declared after the STATIC_INSTANCE. This is a similar technique to the one used by most standard libraries to initialize std::cin and std::cout.
Example:
In sample_header_1a.hpp:
#include <adobe/once.hpp>

ADOBE_ONCE_DECLARATION(signature_1a)
ADOBE_ONCE_STATIC_INSTANCE(signature_1a)

// ... rest of shared header file content
In sample_source_1a.cpp:
void init_once_1a()
{
    // initialization of global variables to initial values
}

// ...

ADOBE_ONCE_DEFINITION(signature_1a, init_once_1a)
1b) ADOBE_ONCE_DECLARATION/STATIC_INSTANCE/DEFINITION (Globally Unshared)
Identical to (1a) except the declaration and instance are placed in the source file rather than in a header file.
Example:
In sample_source_1b.cpp:
#include <adobe/once.hpp>

ADOBE_ONCE_DECLARATION(signature_1b)
ADOBE_ONCE_STATIC_INSTANCE(signature_1b)

// ...

void init_once_1b()
{
    // initialization of global variables to initial values
}

// ...

ADOBE_ONCE_DEFINITION(signature_1b, init_once_1b)
2) ADOBE_ONCE_DECLARATION/INSTANCE/DEFINITION
Used when you have a piece of code that can serve as a bottleneck for the call to the init_once function. For example, use this in a source file when you have unshared global variables supporting a pimpl class. Place ADOBE_ONCE_INSTANCE(sig); inside the pimpl constructor(s).
Example:
In sample_source_2.cpp:
#include <adobe/once.hpp>

ADOBE_ONCE_DECLARATION(signature_2)

// ... 

void init_once_2()
{
    // initialization of global variables to initial values
}

// ... 

my_foo_t::implementation_t::implementation_t()
{
    ADOBE_ONCE_INSTANCE(signature_2); // note the semicolon!

    // ... 
}

// ... 

ADOBE_ONCE_DEFINITION(signature_2, init_once_2)
3) ADOBE_GLOBAL_MUTEX_DEFINITION/GLOBAL_MUTEX_INSTANCE
Used when you have a suite of data you want to initialize then protect in a multithreaded environment. This macro uses an additional mutex to control access to the data during initialization and successive modification. Any code from the instance macro to the end of the scope in which the macro is placed is thread safe.
Example:
In sample_source_3.cpp:
#include <adobe/once.hpp>

ADOBE_GLOBAL_MUTEX_DEFINITION(signature_3)

// ... 

my_function_requiring_thread_safety()
{
    ADOBE_GLOBAL_MUTEX_INSTANCE(signature_3); // note the semicolon!

    // ...
}

Define Documentation

#define ADOBE_GLOBAL_MUTEX_DEFINITION (   signature )

Used in case (3) above.

Creates a translation-unit global mutex that is initialized in a threadsafe manner. In a environments without thread support environment, this macro is empty.

Parameters:
signatureThe unique signature used to relation this macro to other ADOBE_ONCE macros

Definition at line 106 of file once.hpp.

#define ADOBE_GLOBAL_MUTEX_INSTANCE (   signature )

Used in case (3) above.

Locks a scope with the mutex created from ADOBE_GLOBAL_MUTEX_DEFINITION to ensure thread safety of the code contained within said scope. In a environments without thread support environment, this macro is empty.

Parameters:
signatureThe unique signature used to relation this macro to other ADOBE_ONCE macros

Definition at line 107 of file once.hpp.

#define ADOBE_ONCE_DECLARATION (   signature )

Used in cases (1a), (1b), (2) above.

Declares a utility struct for supporting a call to adobe::call_once

Parameters:
signatureThe unique signature used to relation this macro to other ADOBE_ONCE macros

Definition at line 66 of file once.hpp.

#define ADOBE_ONCE_DEFINITION (   signature,
  func 
)

Used in cases (1a), (1b), (2) above.

Defines a utility struct for supporting a call to adobe::call_once with the specified function

Parameters:
signatureThe unique signature used to relation this macro to other ADOBE_ONCE macros
funcThe function to be called only once

Definition at line 72 of file once.hpp.

#define ADOBE_ONCE_INIT

Default setting for the adobe::once_flag. In a thread-aware environment this is the same as BOOST_ONCE_INIT, otherwise it is simply false.

Definition at line 45 of file once.hpp.

#define ADOBE_ONCE_INSTANCE (   signature )

Used in cases (2) above.

Creates an instance of the ADOBE_ONCE utility struct. During construction each instance of this struct will check to see if the one-time function has already been called, and calls it if necessary.

Parameters:
signatureThe unique signature used to relation this macro to other ADOBE_ONCE macros

Definition at line 81 of file once.hpp.

#define ADOBE_ONCE_STATIC_INSTANCE (   signature )

Used in cases (1a), (1b) above.

Creates a tanslation-unit global instance of the ADOBE_ONCE utility struct. Use only once in a single translation-unit for the binary per macro signature.

Parameters:
signatureThe unique signature used to relation this macro to other ADOBE_ONCE macros

Definition at line 84 of file once.hpp.


Typedef Documentation

once_flag

A flag used to guarantee the one-time execution of code. In a thread-aware environment this is the same as a boost::once_flag, otherwise it is simply a bool.

Definition at line 44 of file once.hpp.


Function Documentation

void call_once ( void(*)()  func,
adobe::once_flag flag 
)
Parameters:
funcThe function guaranteed to be executed only one time
flagThe flag to monitor onetime execution of the function
Exceptions:
UnknownPropagates anything func throws

In a thread-aware environment adobe::call_once is the same as boost::call_once. Otherwise it is a simple support function that executes func only once as flagged by flag.

Definition at line 47 of file once.hpp.

Copyright © 2006-2007 Adobe Systems Incorporated.

Use of this website signifies your agreement to the Terms of Use and Online Privacy Policy.

Search powered by Google