NDSStoreAccessSync

public class NDSStoreAccessSync : MapDataStoreAccessSyncing

Synchronizes access to an onboard NDS map.

An object of this class acts as a kind of a reader/writer lock, in that it allows any number of concurrent readers to access the map at the same time, or one writer and nobody else. It also offers facilities for writers to notify all current readers that the map needs to be modified so they (the readers) can ‘let go’. After the writer has finished modifying the map, NDSStoreAccessSync will dispatch notifications to all others to let them know the map is accessible once again.

Important

This is a Public Preview API. It may be changed or removed at any time.

Lifecycle

  • Creates an instance of NDSStoreAccessSync.

    Declaration

    Swift

    public init()

Public

  • Registers an observer so it can be informed about changes in map availability. Caller must register their observer in order to get onReadOnlyAccessGranted access If the caller does not add an observer read access will not be granted . If the map is already available at the time of calling this, onReadOnlyAccessGranted will be called immediately, before this call returns. Caller of this function must not hold the same synchronisation primitive (mutex, lock or similar) which will be held inside callbacks inherited from ‘OnStoreAccessChangedObserver’. Otherwise, a deadlock may occur!

    Throws

    NDSStoreAccessSyncError.invalidObserverError upon adding the same observer more than once.

    Declaration

    Swift

    public func addObserver(_ observer: OnStoreAccessChangedObserver) throws

    Parameters

    observer

    observer to add.

  • Unregisters an observer (if it was previously registered by addObserver).

    After this function returns, it is guaranteed that no more callbacks will be received by this observer.

    Caller of this function must not hold the same synchronisation primitive (mutex, lock or similar) which will be held inside callbacks inherited from ‘OnStoreAccessChangedObserver’. Otherwise, a deadlock may occur!

    Declaration

    Swift

    public func removeObserver(_ observer: OnStoreAccessChangedObserver)

    Parameters

    observer

    observer to remove.

  • Request to obtain write access (in addition to read access) to the map for the given observer. Upon calling this, all other currently registered observers will be asked to release read-only access (via onReadOnlyAccessReleaseRequested) and this call will block until they do so or the time runs out (see: ‘timeout’ parameter).

    Throws

    NDSStoreAccessSyncError.InvalidObserverError upon attempting to request write access for a observer that wasn’t previously added via addObserver.

    Declaration

    Swift

    public func requestWriteAccess(
    observer: OnStoreAccessChangedObserver,
    timeout: TimeInterval
) throws
    -> WriteAccessStatus

    Parameters

    observer

    observer which will be granted write access if the call is successful.
    timeout

    maximum time to wait.

    Return Value

    WriteAccessStatus .granted if the request was successful, .timedOut if the time ran out, or .grantedToAnother if the request was cancelled because a different observer already has write access.

  • Release write access previously obtained by requestWriteAccess (and return to read-only).

    Throws

    NDSStoreAccessSyncError.InvalidObserverError upon attempting to release write access for a observer that wasn’t previously added via addObserver or didn’t previously obtain write access via requestWriteAccess.

    Declaration

    Swift

    public func releaseWriteAccess(observer: OnStoreAccessChangedObserver) throws

    Parameters

    observer

    observer that currently has write access to the map.