LIBASO(3)

NAME
ASO - Atomic Scalar Operations

SYNOPSIS
#include <aso.h> typedef int (*Asoerror_f)(int, const char*); typedef void* (*Asoinit_f)(void*, const char*); typedef ssize_t (*Asolock_f)(void*, ssize_t, void volatile*); typedef struct Asodisc_s {
    uint32_t    version;
    unsigned int    hung;
    Asoerror_f    errorf;
} Asodisc_t; typedef struct Asometh_s {
    const char*    name;
    int    type;
    Asoinit_f    initf;
    Asolock_f    lockf;
    const char*    details;
} Asometh_t;
uint8_t    asocas8(uint8_t volatile*, int, int);
uint8_t    asoget8(uint8_t volatile*);
uint8_t    asoinc8(uint8_t volatile*);
uint8_t    asodec8(uint8_t volatile*);
uint16_t    asocas16(uint16_t volatile*, uint16_t, uint16_t);
uint16_t    asoget16(uint16_t volatile*);
uint16_t    asoinc16(uint16_t volatile*);
uint16_t    asodec16(uint16_t volatile*);
uint32_t    asocas32(uint32_t volatile*, uint32_t, uint32_t);
uint32_t    asoget32(uint32_t volatile*);
uint32_t    asoinc32(uint32_t volatile*);
uint32_t    asodec32(uint32_t volatile*);
uint64_t    asocas64(uint64_t volatile*, uint64_t, uint64_t);
uint64_t    asoget64(uint64_t volatile*);
uint64_t    asoinc64(uint64_t volatile*);
uint64_t    asodec64(uint64_t volatile*);
unsigned char    asocaschar(unsigned char volatile*, int, int);
unsigned char    asogetchar(unsigned char volatile*);
unsigned char    asoincchar(unsigned char volatile*);
unsigned char    asodecchar(unsigned char volatile*);
unsigned short    asocasshort(unsigned short volatile*, unsigned short, unsigned short);
unsigned short    asogetshort(unsigned short volatile*);
unsigned short    asoincshort(unsigned short volatile*);
unsigned short    asodecshort(unsigned short volatile*);
unsigned int    asocasint(unsigned int volatile*, unsigned int, unsigned int);
unsigned int    asogetint(unsigned int volatile*);
unsigned int    asoincint(unsigned int volatile*);
unsigned int    asodecint(unsigned int volatile*);
unsigned long    asocaslong(unsigned long volatile*, unsigned long, unsigned long);
unsigned long    asogetlong(unsigned long volatile*);
unsigned long    asoinclong(unsigned long volatile*);
unsigned long    asodeclong(unsigned long volatile*);
size_t    asocassize(size_t volatile*, size_t, size_t);
size_t    asogetsize(size_t volatile*);
size_t    asoincsize(size_t volatile*);
size_t    asodecsize(size_t volatile*);
void*    asocasptr(void volatile*, void*, void*);
void*    asogetptr(void volatile*);
void    ASODISC(Asodisc_t*, Asoerror_f);
Asometh_t*    asometh(int, void*);
int    asoinit(const char*, Asometh_t*, Asodisc_t*);
int    asolock(unsigned int volatile*, unsigned int, int);
int    asoloop(uintmax_t);
int    asorelax(long);

DESCRIPTION

ASO provides functions to perform atomic scalar operations. The functions on the type uint32_t will be fully described below. Other functions work similarly on their respective types. Some of the functions may be macros that call other functions. 64 bit operations are provided if the compiler supports 64 bit integers and/or pointers.

uint8_t, uint16_t, uint32_t, uint64_t These are unsigned integer types of different sizes in bits. For example, uint32_t represents the type of unsigned integer with 32 bits or 4 bytes.

This function returns the value *from.

These functions increment *dest by 1 and decrement *dest by 1 in an atomic step. The return value is the old value in *dest. Consider an example where two concurrent threads/processes call asoinc32() on the same dest with values, say v1 and v2. The eventual value in dest will be as if *dest += 2 was performed in a single-threaded execution. That should be constrasted with a situation where, instead of asoinc32() or asodec32(), only normal increment (++) or decrement (--) were used. Then, the end result could be either *dest += 1 or *dest += 2, depending on states of the hardware cache and process scheduling.

This function provides the atomic compare-and-swap operation. If the current content of dest is equal to tstval then it will be set to newval. If multiple threads/processes are performing the same operations only one will succeed with a return value of tstval. The return value is the old value in *dest.

This function causes the calling process or thread to briefly pause for nsec nanoseconds. It is useful to implement tight loops that occasionally yield control.

This function uses key, a non-zero unsigned integer, to lock or unlock the lock. It returns 0 on success and -1 on failure. The argument type can take one of the following values: ASO_UNLOCK: This unlocks the lock if it was locked with key. It is an error to try unlocking a lock of a different key. ASO_TRYLOCK: This makes a single attempt to use the given key to acquire a lock. An error will result if the lock is already locked with a different key. ASO_LOCK: This is a regular locking call. If the lock is locked with a different key, this call will wait until the lock is open, then lock it with the given key. ASO_SPINLOCK: Regardless of what key is currently locking the lock, this call will always wait until the lock is open, then lock it with the given key. Note that, if the lock is already locked with key, this call can result in a deadlock unless that lock can be opened by some other mechanism, e.g., by a different process or thread.

This function is used to implement spin locks that periodically relinquish the processor: uintmax_t iteration; iteration = 0; for (;;) {
    /* test resource with an aso*() call */
    if (asoloop(++iteration))
        /* an error occurred */; } The value of iteration should be 1 (not 0) for the first loop iteration. 0 is returned on success, -1 on failure. If iteration mod 4 is 0 then asorelax(1) is called to temporarily relinquish the processor. If Asodisc_t.hung != 0 and Asodisc_t.errorf != 0 and iteration mod (2**Asodisc_t.hung-1) is 0, then Asodisc_t.errorf is called with type ASO_HUNG and -1 is returned.

The Asodisc_t discipline structure allows the caller to modify default behavior. The ASO discipline is global for all threads and forked children of the current process. The discipline is set and modified by the asoinit() function, described below. The structure members are: uint32_t version; This must be set to ASO_VERSION by the caller and is used by the implementation to detect release differences between the caller and the implementation. The version is integer of the form YYYYMMDD where YYYY is the release year, MM is the release month, and DD is the release day of month. This allows the implementation to be forwards and backwards binary compatible with all releases. unsigned int hung; An error occurs if asoloop() is called 2**Asometh_t.hung times without gaining access to the loop resource. The default value 0 disables the test. Asoerror_f errorf; int (*errorf)(int type, const char* mesg); If errorf != 0 then it is called for each ASO fatal library condition. type may be one of: ASO_METHOD - a method error; ASO_HUNG - asoloop() was called 2**Asometh_t.hung times with no access to the loop resource. mesg is a 0-terminated messsage description.

This function-like-macro initializes disc->version = ASO_VERSION, disc->errorf = errorf, and the remaining disc members to 0.

Several atomic locking methods are implemented for atomic operations not supported by intrinsic functions or assembly instructions. Methods are controlled by the asometh() and asoinit() functions, described below. The ASO method is global for all threads and forked children of the current process. A given method may have multiple types. The methods types are: ASO_INTRINSIC: Some hardware platforms provide machine instructions to implement these operations directly. In that case, if a local compiler permits, calls to these intrinsic functions may be translated directly into their corresponding machine instructions. When necessary the implementation can use only the intrinsic compare-and-swap function on the largest integer type to emulate all other ASO operations. The ASO_INTRINSIC method type is the default when supported by the compiler. It may be used for single-process single-thread, multi-thread, and multi-process applications. When supported by the hardware / compiler, the library provides the "intrinsic" method with type ASO_INTRINSIC|ASO_PROCESS|ASO_THREAD|ASO_SIGNAL. ASO_SIGNAL: This method type is suitable only for single-process single-thread applications. It can be used to provide locking between asyncronous signal(2) handlers and the main program. The library provides the "signal" method with type ASO_SIGNAL. This is the default method type when ASO_INTRINSIC is not supported. ASO_THREAD: This method type is suitable for single-process single-thread, and multi-thread applications. It typically requires thread library support, and since the default aso library is not linked with a thread library, no ASO_THREAD method is provided by default. Threaded applications must link with -ltaso (before -laso or -last) in order to access ASO_THREAD methods. The -ltaso library provides the "spin" (using pthread_spin_lock(3)) and "mutex" (using pthread_mutex_lock(3)) methods with type ASO_THREAD|ASO_SIGNAL. ASO_PROCESS: This method type is suitable for single-process single-thread, and multi-process applications. Some ASO_PROCESS methods may also be suitable for multi-thread applications (if they have the ASO_THREAD type.) These methods are typically and noticably slow, up to 2 orders of magnitude slower than ASO_INTRINSIC for some applications. They are provided as a last resort when other methods are not available. The library provides the "semaphore" method with type ASO_PROCESS|ASO_THREAD|ASO_SIGNAL and the "fcntl" method with type ASO_PROCESS|ASO_SIGNAL. This function looks up methods by type or name. If type is 0 and data is 0 then the current method is returned; a valid method will always be returned for this call. If type is 0 then data is treated as a 0-terminated string method name; 0 is returned if no matching method is found. The pseudo-type ASO_NEXT generates the list of all methods in successive calls: Asometh_t* meth; meth = 0; while (meth = asometh(ASO_NEXT, meth))
    /* examine meth->... */ Otherwise if type is not 0 and not ASO_NEXT it is treated as a combination of the ordered types ASO_THREAD, ASO_SIGNAL, ASO_INTRINSIC, ASO_PROCESS: the first method with (meth->type & type) != 0 is returned; 0 is returned if no matching method is found. Method names are treated as a name, optionally followed by a list of ,name=value details, and optionally ending with ,pathname. The semaphore method uses size=number to specify the number of semaphores and hashes pathname to determine the semaphore IPC key. The fcntl method uses size=number to specify the number of 1 byte file locks and uses pathname as the file to lock using fcntl(F_SETLCK[W]). This function sets the global discipline to disc, closes the current method (releasing its resources), temporarily instantiates the default method (either ASO_INTRINSIC if available or AS_SIGNAL otherwise), and initializes meth and instantiates it as the new method. If disc is 0 the the global discpline is not modified. If meth is 0 then 1 is returned if asoinit() has already been called to initialize a method, otherwise 0 is returned. If meth->lockf is 0 and (meth->type & ASO_INTRINSIC) != 0 then -1 is returned and the current method is not changed. If an error occurs instantiating meth then the current method is set to the default and -1 is returned. Otherwise 0 is returned on success. Method resources are released by the next asometh() call, or by an ASO cleanup function called via atexit(2). System global method resources are released on last use; this includes removing semaphore keys or physical files that may be used by some methods. In some cases ASO maintains reference counts within the resource to determine last use. An application requiring a specific method must check the default method before using any ASO operations. For example, a threaded application would do something like this: void* data = 0 /* or a method name string with optional details */ Asometh_t* meth; if (data || !(asometh(0, 0)->type & (ASO_INTRINSIC|ASO_THREAD))) {
    if (!(meth = asometh(ASO_INTRINSIC|ASO_THREAD, data)))
        /* error -- suitable method not found */;
    else if (asoinit(meth, 0, 0, ASO_VERSION))
        /* error -- method initialization error */; } /* ready for ASO operaions */ A multi-process application would check for (ASO_INTRINSIC|ASO_PROCESS) instead of (ASO_INTRINSIC|ASO_THREAD).

IMPLEMENTATION NOTES
Unlike other AST library discipline/method functions which can instantiate multiple discpline/method handles within a single process, the ASO library allows only one discipline and method to be set at a time, with the additional restriction that it may only be set by the main and only thread of the calling process. For this reason there is no open/close interface with an instantation handle; instead the global discipline/method is simply initialized by asoinit(). ASO_THREAD and ASO_PROCESS methods rely on the Asometh_t.lockf() being sufficiently "heavy" to flush the calling thread/process memory cache so the subsequent ASO operation operates on the physical memory location instead of the cached location. There is currently no other portable mechanism that guarantees this other than the ASO_INTRINSIC method.

AUTHOR
Kiem-Phong Vo, Adam Edgar, and Glenn Fowler