Crate ulock_sys

Bindings for macOS’s not-entirely-public ulock API, which provides futex-like functionality.

In general, caveat emptor. It’s recommended that you read both the source and the header. In particular, I’ve not documented the code very much beyond what’s in the headers, aside from supported version indications.

Support

This API is available on darwin 16+ (macOS 10.12+, iOS 10.0+, tvOS 10.0+, watchOS 3.0+, catalyst 13.0+), although some parts are darwin 19+ (macOS 10.15+, iOS 13.0+, TODO: find out the rest). The parts on darwin 19+ are in the darwin19 module (it’s just some additional constants, so not worth feature gating).

That is to say, this is pretty well supported, over 95% of users on both macOS and iOS will have it (according to statscounter as of Jan 2021).

That said, they’re not public, and who knows the future, maybe Apple will remove them. But probably not — they’re also used by libc++, and so if they ever went away, code that statically links libc++ would suddenly break, but… who knows, maybe apple will do it.

“weak” linking, cargo features

As a result of that (and so that you can support older versions), if you enable the experimental-weak feature, we’ll expose a module weak which emulates weak linking and accesses the function via dlsym.

Note that on aarch64 darwin (e.g. “apple silicon”, the ARM64 macbooks and such) by default we don’t dlsym even if the “experimental-weakweak” feature is on unless “weak-aarch64-macos” is also specified. This is because all OSes on these machines support the API. This can be overridden by enabling the weak-aarch64-macos feature.

Note that the API of this crate (except for consts) is behind cfg!(target_vendor = "apple").

Modules

darwin19

The portion of the API only is supported on Darwin 19 and up (macOS 10.15+, iOS 13.0+).

weak

feature = "experimental-weak" Weak linking emulation. See crate docs for info.

Constants

ULF_NO_ERRNO

Generic flag usable with __ulock_wake or __ulock_wait (these are in bits 24-32)

ULF_WAIT_CANCEL_POINT

Flag only for __ulock_wait (these are in bits 16-24).

ULF_WAIT_WORKQ_DATA_CONTENTION

Flag for __ulock_wait (these are in bits 16-24).

ULF_WAKE_ALL

Flag for __ulock_wake (these are in bits 8-16)

ULF_WAKE_THREAD

Flag for __ulock_wake (these are in bits 8-16)

UL_COMPARE_AND_WAIT

Operation code (these are in bits 0-8)

UL_HANDOFFLOCKDeprecated

Obsolete name for UL_UNFAIR_LOCK. Deprecated, but provided for porting.

UL_OSSPINLOCKDeprecated

Obsolete name for UL_COMPARE_AND_WAIT. Deprecated, but provided for porting.

UL_UNFAIR_LOCK

Operation code (these are in bits 0-8)

Functions

__ulock_wait^⚠

__ulock_wake^⚠

Type Aliases

ULockWaitFn

Alias for the function pointer of __ulock_wait.

ULockWakeFn

Alias for the function pointer of __ulock_wake.