Atomic Primitives - SeqAn API Documentation

# Group Atomic Primitives
Portable atomic operations.

## Grouped Function Overview

- `TResult atomicAdd(x, y)`
  Atomically add an integer to another integer.
- `TResult atomicCas(x, cmp, y)`
  Atomic ompare-and-Swap operation.
- `TResult atomicDec(x);`
  Atomically decrement an integer.
- `TResult atomicInc(x);`
  Atomically increment an integer.
- `TResult atomicOr(x, y);`
  Atomically combine two integers with `OR` operation.
- `TResult atomicXor(x, y);`
  Atomically combine two integers with `XOR` operation.

## Grouped Functions Detail

### `TResult atomicAdd(x, y)`

Defined in
  <seqan/parallel.h>

Atomically add an integer to another integer.

#### Parameters

`x` | Integer, by reference.
`y` | Integer to add to `x`.

#### Returns

`TResult` | The old value of `x`.

#### Remarks

This is equivalent to an atomic `x += y`.

Note that atomic fetch-and-add is limited to 32 bit and 64 bit with MSVC (64 bit is only available on 64 bit Windows).

You are responsible for correctly aligning `x` such that the atomic increment works on the hardware you target.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TResult atomicCas(x, cmp, y)`

Defined in
  <seqan/parallel.h>

Atomic ompare-and-Swap operation.

#### Parameters

`x` | Pointer to the integer to swap.
`cmp` | Value to compare `x` with.
`y` | Value to set `x` to if it is equal to `cmp`.

#### Returns

`TResult` | Returns the original value of x.

#### Remarks

The pseudo code for this is as follows:

    atomic {
        T val = *(&x);
        if (val == cmp)
            *(&x) = y;
        return val;
    }

On Windows, atomic CAS is only available for 16, 32, and 64 bit integers, 64 bit is only available on 64 bit Windows.

You are responsible for correctly aligning `x` such that the atomic increment works on the hardware you target.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TResult atomicDec(x);`

Defined in
  <seqan/parallel.h>

Atomically decrement an integer.

#### Parameters

`x` | An integer, by reference.

#### Returns

`TResult` | The old value of $x$, `TResult` has the same type as `x`.

#### Remarks

This is equivalent to an atomic `--x`.

Note that atomic decrements are limited to 32 bit and 64 bit with MSVC (64 bit is only available on 64 bit Windows).

You are responsible for correctly aligning `x` such that the atomic decrement works on the hardware you target.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TResult atomicInc(x);`

Defined in
  <seqan/parallel.h>

Atomically increment an integer.

#### Parameters

`x` | An integer, by reference.

#### Returns

`TResult` | The old value of $x$, `TResult` has the same type as `x`.

#### Remarks

This is equivalent to an atomic `++x`.

Note that atomic increments are limited to 32 bit and 64 bit with MSVC (64 bit is only available on 64 bit Windows).

You are responsible for correctly aligning `x` such that the atomic increment works on the hardware you target.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TResult atomicOr(x, y);`

Defined in
  <seqan/parallel.h>

Atomically combine two integers with `OR` operation.

#### Parameters

`x` | Integer, by reference.
`y` | Integer to combine with `OR` operation.

#### Returns

`TResult` | The old value of `x`, `TResult` is the type of `x`.

#### Remarks

This is equivalent to an atomic `x |= y`.

Atomic fetch-and-or for 64 bit integers is only available on 64 bit processors when targeting Intel.

Atomic fetch-and-or does not work in VS8 on 64 bit Windows, you can only use `atomicOr()` portably on 32 and 64 bit integers.

You are responsible for correctly aligning `x` such that the atomic increment works on the hardware you target.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TResult atomicXor(x, y);`

Defined in
  <seqan/parallel.h>

Atomically combine two integers with `XOR` operation.

#### Parameters

`x` | Integer, by reference.
`y` | Integer to combine with `XOR` operation.

#### Returns

`TResult` | The old value of `x`, `TResult` is the type of `x`.

#### Remarks

This is equivalent to an atomic `x ^= y`.

Atomic fetch-and-xor fxor 64 bit integers is only available on 64 bit processxors when targeting Intel.

Atomic fetch-and-xor does not wxork in VS8 on 64 bit Windows, you can only use `atomicXor()` pxortably on 32 and 64 bit integers.

You are responsible fxor cxorrectly aligning `x` such that the atomic increment wxorks on the hardware you target.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### Dox Sources

    /*!
     * @defgroup AtomicPrimitives Atomic Primitives
     *
     * @brief Portable atomic operations.
     *
     * @fn AtomicPrimitives#atomicInc
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Atomically increment an integer.
     *
     * @signature TResult atomicInc(x);
     *
     * @param[in,out] x An integer, by reference.
     *
     * @return TResult The old value of $x$, <tt>TResult</tt> has the same type as
     *                 <tt>x</tt>.
     *
     * @section Remarks
     *
     * This is equivalent to an atomic <tt>++x</tt>.
     *
     * Note that atomic increments are limited to 32 bit and 64 bit with MSVC (64
     * bit is only available on 64 bit Windows).
     *
     * You are responsible for correctly aligning <tt>x</tt> such that the atomic
     * increment works on the hardware you target.
     *
     * @fn AtomicPrimitives#atomicDec
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Atomically decrement an integer.
     *
     * @signature TResult atomicDec(x);
     *
     * @param[in,out] x An integer, by reference.
     *
     * @return TResult The old value of $x$, <tt>TResult</tt> has the same type as
     *                 <tt>x</tt>.
     *
     * @section Remarks
     *
     * This is equivalent to an atomic <tt>--x</tt>.
     *
     * Note that atomic decrements are limited to 32 bit and 64 bit with MSVC (64
     * bit is only available on 64 bit Windows).
     *
     * You are responsible for correctly aligning <tt>x</tt> such that the atomic
     * decrement works on the hardware you target.
     *
     * @fn AtomicPrimitives#atomicAdd
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Atomically add an integer to another integer.
     *
     * @signature TResult atomicAdd(x, y)
     *
     * @param[in,out] x Integer, by reference.
     * @param[in] y Integer to add to <tt>x</tt>.
     *
     * @return TResult The old value of <tt>x</tt>.
     *
     * @section Remarks
     *
     * This is equivalent to an atomic <tt>x += y</tt>.
     *
     * Note that atomic fetch-and-add is limited to 32 bit and 64 bit with MSVC (64
     * bit is only available on 64 bit Windows).
     *
     * You are responsible for correctly aligning <tt>x</tt> such that the atomic
     * increment works on the hardware you target.
     *
     * @fn AtomicPrimitives#atomicOr
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Atomically combine two integers with <tt>OR</tt> operation.
     *
     * @signature TResult atomicOr(x, y);
     *
     * @param[in,out] x Integer, by reference.
     * @param[in] y Integer to combine with <tt>OR</tt> operation.
     *
     * @return TResult The old value of <tt>x</tt>, <tt>TResult</tt> is the type of
     *                 <tt>x</tt>.
     *
     * @section Remarks
     *
     * This is equivalent to an atomic <tt>x |= y</tt>.
     *
     * Atomic fetch-and-or for 64 bit integers is only available on 64 bit
     * processors when targeting Intel.
     *
     * Atomic fetch-and-or does not work in VS8 on 64 bit Windows, you can only use
     * <tt>atomicOr()</tt> portably on 32 and 64 bit integers.
     *
     * You are responsible for correctly aligning <tt>x</tt> such that the atomic
     * increment works on the hardware you target.
     *
     * @fn AtomicPrimitives#atomicXor
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Atomically combine two integers with <tt>XOR</tt> operation.
     *
     * @signature TResult atomicXor(x, y);
     *
     * @param[in,out] x Integer, by reference.
     * @param[in] y Integer to combine with <tt>XOR</tt> operation.
     *
     * @return TResult The old value of <tt>x</tt>, <tt>TResult</tt> is the type of
     *                 <tt>x</tt>.
     *
     * @section Remarks
     *
     * This is equivalent to an atomic <tt>x ^= y</tt>.
     *
     * Atomic fetch-and-xor fxor 64 bit integers is only available on 64 bit
     * processxors when targeting Intel.
     *
     * Atomic fetch-and-xor does not wxork in VS8 on 64 bit Windows, you can only
     * use <tt>atomicXor()</tt> pxortably on 32 and 64 bit integers.
     *
     * You are responsible fxor cxorrectly aligning <tt>x</tt> such that the atomic
     * increment wxorks on the hardware you target.
     *
     * @fn AtomicPrimitives#atomicCas
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Atomic ompare-and-Swap operation.
     *
     * @signature TResult atomicCas(x, cmp, y)
     *
     * @param[in,out] x Pointer to the integer to swap.
     * @param[in,out] cmp Value to compare <tt>x</tt> with.
     * @param[in] y Value to set <tt>x</tt> to if it is equal to <tt>cmp</tt>.
     *
     * @return TResult Returns the original value of x.
     *
     * @section Remarks
     *
     * The pseudo code for this is as follows:
     *
     * @code{.cpp}
     * atomic {
     *     T val = *(&x);
     *     if (val == cmp)
     *         *(&x) = y;
     *     return val;
     * }
     * @endcode
     *
     *
     * On Windows, atomic CAS is only available for 16, 32, and 64 bit integers, 64
     * bit is only available on 64 bit Windows.
     *
     * You are responsible for correctly aligning <tt>x</tt> such that the atomic
     * increment works on the hardware you target.
     */