View source for r7.1.1:Macro LFDS711 PAL ATOMIC SET

{{DISPLAYTITLE:macro LFDS711_PAL_ATOMIC_SET}}
==Source File==
 └───liblfds711
     └───inc
         └───liblfds711
                 lfds711_porting_abstraction_layer_compiler.h

==Macro==
 #define LFDS711_PAL_ATOMIC_SET( pointer_to_destination, exchange )  [compiler atomic exchange (not set - see below) instrinsic]

==Parameters==
''pointer_to_destination''
: The address of a ''liblfds711_pal_uint_t volatile'', which ''*pointer_to_exchange'' will be written to.

''exchange''
: A ''liblfds711_pal_uint_t'' which will be written into ''*pointer_to_destination''.

==Return Value==
No return value.

==Example==
 #define LFDS711_PAL_ATOMIC_SET( pointer_to_destination, new_value )        \
 {                                                                          \
   LFDS711_PAL_BARRIER_COMPILER_FULL;                                       \
   (void) __sync_lock_test_and_set( pointer_to_destination, (new_value) );  \
   LFDS711_PAL_BARRIER_COMPILER_FULL;                                       \
 }

==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 prototyped doesn't map directly to the atomic intrinsic prototype for that platform).

The actual atomic intrinsic 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.

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.

The SET operation is really an EXCHANGE but where the original value is thrown away.  This turns out to be useful in terms of C syntax.  As mentioned above, all of the atomic macros are defined with curley braces.  As such they cannot return values - rather, a pointer must be passed in, and the variable pointer to set to the value returned.  Unfortunately, though, in the source code, a number of different variable types are passed to EXCHANGE, and this, combined with strict aliasing, leads to irreconcilable warnings.  Either there's a warning about types, or a warning about breaking strict aliasing.  The SET macro however throws away the return value and so this problem goes away, reducing the use of EXCHANGE to only situations where there are no variable type warnings.

There is in ''libtest'' no test for the behaviour of this macro.  This is because it is impossible to test that a SET-style semantic macro is working correctly, as the original value is not available.  It is possible to test an EXCHANGE-style semantic macro, because the original value is returned, and this test exists in ''libtest''.  When implementing this macro, take the EXCHANGE macro, which should be passing its test, and simply throw away the return value.  Some compilers require the return value to be cast to ''(void)'', or they will throw a warning, and this can be seen in the example.

==See Also==
* [[r7.1.1:Porting Guide (liblfds)|Porting Guide (liblfds)]]