 |
Diffusion Apple API
6.3.9
Unified Client Library for iOS, tvOS and OS X / macOS
|
|
Diffusion Apple API
6.3.9
Unified Client Library for iOS, tvOS and OS X / macOS
|
The Topic Update feature provides a client session with the ability to update topics.
Topics can be set to new values using stateless set operations or by using an update stream. Both mechanisms ensure that new values are applied safely to appropriate topics.
An update stream is created for a specific topic. The type of the topic must match the type of values passed to the update stream. An update stream can be used to send any number of updates. It sends a sequence of updates for a specific topic to the server. If supported by the data type, updates will be sent to the server as a stream of binary deltas.
Update streams have additional ways of failing compared to stateless set operations but when used repeatedly have lower overheads. This is because update streams maintain a small amount of state that reduces the overhead of operations but can become invalid for example, if the topic is deleted, or some other session updates the topic value.
By default, update streams use a form of optimistic locking. An update stream can update its topic incrementally as long as nothing else updates the topic. If the topic is updated independently (for example, by another session, or by the current session via set or a different update stream), then the next update performed by the update stream will complete with an 'invalid update stream' error.
Applications can chose to use collaborative locking to coordinate exclusive access to a topic. To follow this pattern acquire a PTDiffusionSessionLock and use it with a lockedWithLock: (PTDiffusionUpdateConstraint) constraint. The application is responsible for designing a locking scheme which determines which lock is required to access a particular topic, and for ensuring that all parts of the application that update the topic follow this scheme. Lock constraints and an application locking scheme can also ensure a sequence of set operations has exclusive access to the topic.
Constraints can be applied to the setting of a value and creation of an update stream. Constraints describe a condition that must be satisfied for the operation to succeed. The constraints are evaluated on the server. The available constraints are:
When a PTDiffusionTopicType_String, PTDiffusionTopicType_Int64 or PTDiffusionTopicType_Double topic is set to nil, the topic will be updated to have no value. If a previous value was present subscribers will receive a notification that the new value is nil. New subscribers will not receive a value notification.
When setting a value using either stateless operations or update streams it is possible to add a topic if one is not present. This is done using the 'and and set' methods or providing a topic specification when creating the update stream. If a topic exists these methods will update the existing topic.
Time series topics have a specific update protocol and are not supported by this feature. Use PTDiffusionTimeSeriesFeature to update time series topics.
To update a topic a session needs UPDATE_TOPIC permission for the topic path. To create a topic a session needs MODIFY_TOPIC permission for the topic path. Requests that combine adding a topic and setting the value, such as those sent by the 'add and set' methods, require both permissions.
The Topic Update feature for a session can be obtained from the session's topicUpdate property.
This feature is also extended by PTDiffusionTopicsFeature. This means it is possible to use the methods described here through that feature.
Additional Inherited Members | |
 Class Methods inherited from PTDiffusionFeature | |
| (instancetype) | + NS_UNAVAILABLE |
| Properties inherited from PTDiffusionFeature | |
| PTDiffusionSession * | session |
| Instance Methods inherited from PTDiffusionFeature | |
| (instancetype) | - NS_UNAVAILABLE |
1.8.5
