NAME

docs/pdds/pdd??_atomic.pod - Atomic operations

ABSTRACT

This document defines a portable interface for accessing atomic operations from parrot backend code.

VERSION

$Revision: 17085 $

DESCRIPTION

Most architectures support atomic updates (read-and-write) to a memory location which do not require the overhead of ordinary locking, even on SMP systems. This document describes an interface for performing a set of such operations on pointers and integers (of some unspecified width which is at least 16 bits). All accesses below are guaranteed to be atomic with respect to each other.

All of the below will be defined by parrot/atomic.h with implementations in parrot/atomic/TYPE.h and, should it be necessary to implement these outside of macros, atomic/TYPE.c.

Types

Parrot_atomic_pointer

Holds a void * value. Must be accessed through macros only.

Parrot_atomic_integer

Holds an integer which is at least 16 bits wide. Must be accessed through macros only.

Macros for accessing atomic values

PARROT_ATOMIC_PTR_INIT(a_ptr)

Initialize a Parrot_atomic_pointer. Must be called before any other use and cannot be used again on the value until PARROT_ATOMIC_PTR_DESTROY() is called. Does not guarantee that PARROT_ATOMIC_PTR_GET(a_ptr) will return any particular value.

PARROT_ATOMIC_PTR_DESTROY(a_ptr)

Destroy any resources associated with a Parrot_atomic_pointer.

PARROT_ATOMIC_PTR_GET(result, a_ptr)

Stores the pointer in a_ptr into result.

PARROT_ATOMIC_PTR_SET(a_ptr, new_value)

Sets the value store in a Parrot_atomic_pointer to new_value.

PARROT_ATOMIC_PTR_CAS(result, a_ptr, old_value, new_value)

``Compare-and-swap''. If the value in a_ptr was old_value, set it to new_value and assign true to result; otherwise assign false to result. (The result is not the return value of this macro so that it can be easily implemented without requiring a function call.)

PARROT_ATOMIC_INT_INIT(a_int)

Initialize a Parrot_atomic_integer. Must be called before any other use and cannot be used again on the same value until PARROT_ATOMIC_INT_DESTROY() is called. Does not guarantee that PARROT_ATOMIC_INT_GET(a_int) will return any particular value.

PARROT_ATOMIC_INT_GET(result, a_int)

Stores the integer in a_int into result.

PARROT_ATOMIC_INT_SET(a_int, new_value)

Stores new_value.

PARROT_ATOMIC_INT_CAS(result, a_int, old_value, new_value)

``Compare-and-swap''. Same as PARROT_ATOMIC_PTR_CAS but with integers.

PARROT_ATOMIC_INT_INC(result, a_int)

Increment the integer atomically. Return the new value in result.

PARROT_ATOMIC_INT_DEC(result, a_int)

Decrement the integer atomically. Return the new value in result.

Feature test macros

PARROT_HAS_NATIVE_ATOMIC

Expands to a true value if this implementation has a native implementation of the atomic operations. Expands to false if the atomic operations are defined in terms of threading primitives. If false, the atomic operations should not be used if the implementors have written an alternative. This will always be 1 when parrot is compiled without threading support in which case the atomic operations will not actually be atomic.

PARROT_HAS_ATOMIC_...

Defined (to a true value) only if the operation by that name is implemented.

IMPLEMENTATION

On most systems with native atomic operation support, Parrot_atomic_pointer and Parrot_atomic_integer will be a struct containing a single integer or pointer and ATOMIC_*_INIT will do nothing. For the fallback implementation the atomic types will be implemented in terms of a Parrot_mutex. Platform-specific implementations should not make Parrot_atomic_pointer or Parrot_atomic_integer a typedef for an integer or pointer type to prevent programmers from accidentally violating encapsulation. =cut

__END__ Local Variables: fill-column:78 End: vim: wrap textwidth=78