Overview

General Project Information

OPA (or sometimes OpenPA or Open Portable Atomics) is an open source library intended to provide a consistent C API for performing atomic operations on a variety of platforms. The main goal of the project is to enable the portable usage of atomic operations in concurrent software. Developers of client software can worry about implementing and improving their concurrent algorithms instead of fiddling with inline assembly syntax and learning new assembly dialects in order improve or maintain application portability.

Several goals and principles have driven OPA design and development:

• Broad portability. We strive to make OPA work well on as many platforms as we reasonably can.
• Minimization of client code complexity. You shouldn't need to write a complicated series of preprocessor feature checks when using OPA. The library should look and act basically the same across different platforms, including the case where you need a fast single-threaded implementation.
• Reduction of client programming errors where possible. The OPA_int_t/OPA_ptr_t types are an example of a safety feature in the API.
• High Performance. At the end of the day the whole reason to considering using OPA is because higher performance is desired in concurrent software. While OPA will never be able to exceed the performance of hand-tuned assembly routines, it should be able to match that performance or at least come very close. This goal is a high priority although it occasionally is superseded by portability or complexity concerns.

Source Layout

OPA is a relatively small project in terms of number of source files and lines of source code. It is primarily organized into three directories:

• src/ contains most of the user API. The important file here is {{{opa_primitives.h}}}
• src/primitives/ contains atomic primitive implementations for various platforms, usually one platform per file
• test/ contains the OPA test suite. This test suite is extremely useful for debugging and general development.

OPA is an autoconfiscated project and requires autoconf >=2.62 and a relatively modern version of automake (>= 1.10 should be fine). The bulk of the user interface lives in header files and is heavily conditionally compiled based on the platform's characteristics, which is normally a problem for autotools projects when installed. However we use the [source:trunk/confdb/ax_prefix_config_h.m4 AX_PREFIX_CONFIG_H macro] to make OPA installations safe for use with other autoconfiscated projects.

(Microsoft Windows is supported but the build system is not currently in place. Please contact us if you need help with this or wish to contribute to the build system.)

Usage

Most users of OPA will only ever need to deal with one file, opa_primitives.h. You can use it in your software with the following line:

#include "opa_primitives.h"

as long as the installation $(includedir) is in your compiler's include path.

There are two atomic types that are defined by and used with the OPA API: OPA_int_t and OPA_ptr_t. An example usage of these types and several of the atomic operations can be found in the sanity.c test.

See the large comment in opa_primitives.h for a complete list of the available atomic operations.

If you are having trouble using OPA, please mail the list so that we can get your straightened out and possibly update the documentation as needed.