Diffusion Apple API  6.3.3
Unified Client Library for iOS, tvOS and OS X / macOS
 All Classes Functions Variables Properties Pages
Class Methods | Properties | Instance Methods | List of all members
PTDiffusionSessionLock Class Reference

Introduction

A server-managed resource that can be used to coordinate exclusive access to shared resources across sessions.

For example, to ensure a single session has the right to update a topic; to ensure at most one session responds to an event; or to select a single session to perform a housekeeping task. Session locks support general collaborative locking schemes. The application architect is responsible for designing a suitable locking scheme and for ensuring each application component follows the scheme appropriately.

Session locks are identified by a lock name. Lock names are arbitrary and chosen at will to suit the application. Each lock is owned by at most one session. Locks are established on demand; there is no separate operation to create or destroy a lock.

A session lock is acquired using the lockWithName:completionHandler: (PTDiffusionSession) method. If no other session owns the lock, the server will assign the lock to the calling session immediately. Otherwise, the server will record that the session is waiting to acquire the lock. A session can call lock more than once for a given session lock; if the lock is acquired, all calls will complete successfully with equal PTDiffusionSessionLock instances.

If a session closes, the session locks it owns are automatically released. A session can also release a lock using the unlockWithCompletionHandler: (PTDiffusionSessionLock) method. When a session lock is released and other sessions are waiting to acquire the lock, the server will arbitrarily select one of the waiting sessions and notify it that it has acquired the lock. All of the newly selected session's pending lock calls will complete normally. Other sessions will continue to wait.

The lockWithName:scope:completionHandler: (PTDiffusionSession) method takes a scope parameter that provides the further option of automatically releasing the lock when the session loses its connection to the server.

There is no association between a lock and a thread. If a session calls lock for a lock it already owns, the call will complete normally and immediately with a PTDiffusionSessionLock instance that is equal to the one returned when the lock was originally acquired. A single call to unlock will release this session's claim to a lock.

Lock ownership can be lost due to an independent event such as loss of connection, and not only due to the use of the locking API by the owner. Consequently, the session should poll using owned to check that it still owns the lock before accessing the protected resource.

Race conditions

This session lock API has inherent race conditions. Even if an application is coded correctly to protect a shared resource using session locks, there may be a period where two or more sessions concurrently access the resource. The races arise for several reasons including

Despite this imprecision, session locks provide a useful way to coordinate session actions.

Since
6.3
Inheritance diagram for PTDiffusionSessionLock:

Class Methods

(instancetype) + NS_UNAVAILABLE
 

Properties

NSString * name
 
SInt64 sequence
 
BOOL owned
 
PTDiffusionSessionLockScopescope
 

Instance Methods

(instancetype) - NS_UNAVAILABLE
 
(void) - unlockWithCompletionHandler:
 
(BOOL) - isEqualToSessionLock:
 

Method Documentation

- (BOOL) isEqualToSessionLock: (nullable PTDiffusionSessionLock *)  sessionLock

Compares the receiver to the given session lock.

Parameters
sessionLockThe session lock object with which to compare the receiver.
Returns
YES if the session lock is equal to the receiver, otherwise NO.
Since
6.3
- (void) unlockWithCompletionHandler: (NSNumber *_Nullable)  wasOwned
(NSError *_Nullable error)  completionHandler 

Release the session lock, if owned.

Parameters
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.

On successful completion, this session will no longer own the named session lock, and wasOwned will wrap a BOOL value where YES indicates this session previously owned the lock and NO indicates that it did not.

On completion with failure, this session does not own the session lock. The common reason for failure, indicated by the error reported, is that the session is closed.

Exceptions
NSInvalidArgumentExceptionRaised if completionHandler is nil.
Since
6.3

Property Documentation

- (NSString*) name
readnonatomicassign

The name of the session lock.

Since
6.3
- (BOOL) owned
readatomicassign

Whether the session lock is still owned by the session. This method may be manually polled but does not support KVO.

Since
6.3
- (PTDiffusionSessionLockScope*) scope
readnonatomicassign

The scope of the lock.

The scope determines when the lock will be released automatically.

If a session makes multiple lock requests for a lock using different scopes, and the server assigns the lock to the session fulfilling the requests, the lock will be given the weakest scope (unlockOnConnectionLoss (PTDiffusionSessionLockScope)). Consequently, an individual request can complete with a lock that has a different scope to that requested.

See Also
- lockWithName:scope:completionHandler: (PTDiffusionSession)
Since
6.3
- (SInt64) sequence
readnonatomicassign

A value that identifies the acquisition of the lock with the given name. Session locks that are acquired later are guaranteed to have bigger sequence values, allowing the sequence number to be used as a fencing token.

Since
6.3