--- name: "aso" section: "3" platform: "macos" package: "ksh" version: "42" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/aso" --- # aso(3) Atomic Scalar Operations ## NAME **ASO** - Atomic Scalar Operations ## SYNOPSIS ``` #include ``` ### 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); ``` ## 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. ### 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)](/signal/2.md) 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)](/pthread_spin_lock/3.md)) and "**mutex"** (using [**pthread\_mutex\_lock**(3)](/pthread_mutex_lock/3.md)) 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 */ ``` 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