OSUnfairLock

public struct OSUnfairLock<State> : @unchecked Sendable

An OSUnfairLock is a wrapper around an unfair lock that locks around accesses to a stored object. It has the same API as OSAllocatedUnfairLock.

Despite being a struct, it isn’t a value type, as copied instances control the same underlying lock allocation.

Prefer storing state protected by the lock in State. Containing locked state inside the lock helps track what is protected state and provides a scope where it is safe to access that state.

When using OSUnfairLock with external state, nonscoped locking allows more flexible locking patterns by using lock() / unlock(), but offers no assistance in tracking what state is protected by the lock.

This lock must be unlocked from the same thread that locked it. As such, it is unsafe to use lock() / unlock() across an await suspension point. Instead, use withLock to enforce that the lock is only held within a synchronous scope.

If you are using a lock from asynchronous contexts only, prefer using an actor instead.

This lock is not a recursive lock. Attempting to lock it again from the same thread while the lock is already locked will crash.

  • Initialize an OSAllocatedUnfairLock with a non-sendable lock-protected initialState.

    By initializing with a non-sendable type, the owner of this structure must ensure the Sendable contract is upheld manually. Non-sendable content from State should not be allowed to escape from the lock.

    Declaration

    Swift

    public init(uncheckedState initialState: State)

    Parameters

    initialState

    An initial value to store that will be protected under the lock.

  • Perform a closure while holding this lock. This method does not enforce sendability requirement on closure body and its return type. The caller of this method is responsible for ensuring references to non-sendables from closure uphold the Sendability contract.

    Throws

    Anything thrown by body.

    Declaration

    Swift

    public func withLockUnchecked<R>(_ body: (inout State) throws -> R) rethrows -> R

    Parameters

    body

    A closure to invoke while holding this lock.

    Return Value

    The return value of body.

  • Perform a sendable closure while holding this lock.

    Throws

    Anything thrown by body.

    Declaration

    Swift

    public func withLock<R>(
    // swiftformat:disable:next spaceAroundParens
    _ body: @Sendable (inout State) throws -> R
) rethrows -> R where R: Sendable

    Parameters

    body

    A sendable closure to invoke while holding this lock.

    Return Value

    The sendable return value of body.

  • Attempt to acquire the lock, if successful, perform a closure while holding the lock. This method does not enforce sendability requirement on closure body and its return type. The caller of this method is responsible for ensuring references to non-sendables from closure uphold the Sendability contract.

    Throws

    Anything thrown by body.

    Declaration

    Swift

    public func withLockIfAvailableUnchecked<R>(_ body: (inout State) throws -> R) rethrows -> R?

    Parameters

    body

    A closure to invoke while holding this lock.

    Return Value

    If the lock is acquired, the result of body. If the lock is not acquired, nil.

  • Attempt to acquire the lock, if successful, perform a sendable closure while holding the lock.

    Throws

    Anything thrown by body.

    Declaration

    Swift

    public func withLockIfAvailable<R>(_ body: (inout State) throws -> R) rethrows -> R? where R : Sendable

    Parameters

    body

    A closure to invoke while holding this lock.

    Return Value

    If the lock is acquired, the result of body. If the lock is not acquired, nil.

  • Check a precondition about whether the calling thread is the lock owner.

    • If the lock is currently owned by the calling thread:
      • .owner - returns
      • .notOwner - asserts and terminates the process
    • If the lock is unlocked or owned by a different thread:
      • .owner - asserts and terminates the process
      • .notOwner - returns

    Declaration

    Swift

    public func precondition(_ condition: Ownership)

    Parameters

    condition

    An Ownership statement to check for the current context.

  • Represent ownership status for precondition checking.

    See more

    Declaration

    Swift

    public enum Ownership : Hashable, Sendable

Available where State == Sendable

  • Initialize an OSAllocatedUnfairLock with a lock-protected sendable initialState.

    Declaration

    Swift

    public init(initialState: State)

    Parameters

    initialState

    An initial value to store that will be protected under the lock.

Available where State == Void

  • Initialize an OSAllocatedUnfairLock with no protected state.

    Declaration

    Swift

    public init()

  • Declaration

    Swift

    public func withLock<R>(
    // swiftformat:disable:next spaceAroundParens
    _ body: @Sendable () throws -> R
) rethrows -> R where R: Sendable

  • Acquire this lock.

    Declaration

    Swift

    public func lock()

  • Unlock this lock.

    Declaration

    Swift

    public func unlock()

  • Attempt to acquire the lock if it is not already locked.

    Declaration

    Swift

    public func lockIfAvailable() -> Bool

    Return Value

    true if the lock was succesfully locked, and false if the lock attempt failed.