macro LFDS711_PAL_ATOMIC_ADD
Source File
└───liblfds711
└───inc
└───liblfds711
lfds711_porting_abstraction_layer_compiler.h
Macro
#define LFDS711_PAL_ATOMIC_ADD( pointer_to_target, value, result, result_type )
Parameters
pointer_to_target
- A pointer to a lfds711_pal_uint_t volatile. The value pointed to by this argument will have the value of the value argument added to it.
value
- A lfds711_pal_uint_t. The number to add to the value pointed to by target.
result
- A lfds711_pal_uint_t. This variable is set to the result of the addition of *target and value.
result_type
- To avoid compiler warnings about types, the type of result must be given, so it can be used in a cast. This is the actual type, a la sizeof().
Return Value
No return value.
Example
#define LFDS711_PAL_ATOMIC_ADD( pointer_to_target, value, result, result_type ) \
{ \
(result) = (result_type) __atomic_add_fetch( (pointer_to_target), (value), __ATOMIC_RELAXED ); \
}
Optionality
This macro is optional. If it is not given, the macro must be absent, rather than empty.
Notes
All of the atomic operation macros open and close with curley braces as some of them need to declare variables on the stack, so that they can operate in ways which match their 'prototype' (i.e. they may need a bit of temporary storage, as the way in which the macro is arranged to work doesn't map directly to the atomic intrinsic prototype for that platform). We see this here in the example.
The actual atomic intrinsic if it does not inherently provide compiler barriers itself MUST be immediately preceeded and followed by LFDS711_PAL_BARRIER_COMPILER_FULL. This is to prevent compiler re-ordering.
Finally, we get to the actual atomic operation itself. The liblfds711_pal_uint_t types need to be cast to the types the intrinsic expects, and to the maximum extent possible eschew any memory barriers. On ARM, for example, memory barriers and atomic operations are wholly seperated and on that platform, the operation is and is only an atomic operation. The data structures themselves issue memory barriers as and when they must, and any additional barriers issued within the atomic macros are only overhead. On x86 and x64, sadly, memory barriers are built into the atomic operations and cannot be removed. On Itanium, it looks like atomic operations must occur with a barrier, but it is possible to choose a load, store or full barrier, and as such on that platform, the load barrier is always used, as it is the lowest cost of the three.
In this particular example, which is for GCC versions equal to or greater than 4.1.2 and less than 4.7.3, we see the compiler intrinsic returns the original value of the destination, but the macro requires this value to be written into the compare variable. It seems strange that the macro is using a pointer to compare - it could just be using compare directly. The reason for this is to be similar in style to the LFDS711_PAL_ATOMIC_DWCAS macro; some DWCAS implementations, where they take an array of two atomic variables, take a pointer for their compare argument and write the original value of destination back to the compare argument, as it cannot (by being an array of two variables) be returned.
If this atomic operaton is not available, the macro must be left undefined, which will lead to a placeholder version automatically being used. This placeholder version if called first calls LFDS711_PAL_ASSERT and then, assuming execution has continued (i.e. LFDS711_PAL_ASSERT is not defined, or is defined but this is a release user-mode build and so asserts are not being checked) will attempt to write 0 into memory location 0, to deliberately crash.