TYPES¶

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;

OPERATIONS¶

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);

TYPES¶

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.

OPERATIONS¶

uint32_t asoget32(uint32_t* from);¶

This function returns the value *from.

uint32_t asoinc32(uint32_t* dest);¶

uint32_t asodec32(uint32_t* dest);¶

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.

uint32_t asocas32(uint32_t* dest, uint32_t tstval, uint32_t newval);¶

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.

void asorelax(long nsec)¶

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.

int asolock(unsigned int* lock, unsigned int key, int type)¶

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.

int asoloop(uintmax_t iteration);¶

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.

DISCIPLINE¶

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.

void ASODISC(Asodisc_t* disc, Asoerror_f errorf);¶

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

METHODS¶

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.

Asometh_t* asometh(int type, void* data);¶

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]).

int asoinit(const char* details, Asometh_t* meth, Asodisc_t* disc);¶

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 */