YapDatabaseCloudCorePipeline

@interface YapDatabaseCloudCorePipeline : NSObject

A pipeline represents a queue of operations for syncing with a cloud server. It operates by managing a series of graphs.

Generally speaking, a graph is all the cloud operations that were generated in a single commit (for a specific pipeline). Within the graph are the various operations with their different dependencies & priorities. The operations within a graph will be executed in accordance with the set dependencies & priorities.

The pipeline manages executing the operations within each graph.

Configuration

  • If you decide to rename a pipeline, you should be sure to set the previousNames property. This is to ensure that operations (from previous app launches) that were tagged with the previous pipeline name can be properly migrated to the new pipeline name.

    This property must be set before the pipeline is registered.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSSet *previousNames;

    Swift

    var previousNames: Set<AnyHashable>? { get set }

  • This value is the maximum number of operations that will be assigned to the delegate at any one time.

    The pipeline keeps track of operations that have been assigned to the delegate (via startOperation:forPipeline:), and will delay assigning any more operations once the maxConcurrentOperationCount has been reached. Once an operation is completed (or skipped), the pipeline will automatically resume.

    Of course, the delegate is welcome to perform its own concurrency restriction. For example, via NSURLSessionConfiguration.HTTPMaximumConnectionsPerHost. In which case it may simply set this to a high enough value that it won’t interfere with its own implementation.

    This value may be changed at anytime.

    The default value is 8.

    Setting the value to zero is the equivalent of setting the value to NSUIntegerMax. If your intention is to pause/suspend the queue, use the suspend/resume methods.

    Declaration

    Objective-C

    @property (assign, readwrite, atomic) NSUInteger maxConcurrentOperationCount;

    Swift

    var maxConcurrentOperationCount: UInt { get set }

Operation Searching

  • Searches for an operation with the given UUID.

    Declaration

    Objective-C

    - (nullable YapDatabaseCloudCoreOperation *)operationWithUUID:
    (nonnull NSUUID *)uuid;

    Swift

    func operation(with uuid: UUID) -> YapDatabaseCloudCoreOperation?

    Return Value

    The corresponding operation, if found. Otherwise nil.

  • Searches for a list of operations.

    Declaration

    Objective-C

    - (nonnull NSDictionary<NSUUID *, YapDatabaseCloudCoreOperation *> *)
    operationsWithUUIDs:(nonnull NSArray<NSUUID *> *)uuids;

    Swift

    func operations(with uuids: [UUID]) -> [UUID : YapDatabaseCloudCoreOperation]

    Return Value

    A dictionary with all the found operations. Operations which were not found won’t be present in the returned dictionary.

  • Returns a list of operations in state ‘YDBCloudOperationStatus_Active’.

    Declaration

    Objective-C

    - (nonnull NSArray<YapDatabaseCloudCoreOperation *> *)activeOperations;

    Swift

    func activeOperations() -> [YapDatabaseCloudCoreOperation]

  • Enumerates the queued operations.

    This is useful for finding operation. For example, you might use this to search for an upload operation with a certain cloudPath.

    Declaration

    Objective-C

    - (void)enumerateOperationsUsingBlock:
    (nonnull void (^)(YapDatabaseCloudCoreOperation *_Nonnull, NSUInteger,
                      BOOL *_Nonnull))enumBlock;

    Swift

    func enumerateOperations(_ enumBlock: (YapDatabaseCloudCoreOperation, UInt, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Returns the number of graphs queued in the pipeline. Each graph represents the operations from a particular commit.

    Declaration

    Objective-C

    - (NSUInteger)graphCount;

    Swift

    func graphCount() -> UInt

Operation Status

  • Returns the current status for the given operation.

    Declaration

    Objective-C

    - (YDBCloudCoreOperationStatus)statusForOperationWithUUID:
    (nonnull NSUUID *)opUUID;

    Swift

    func statusForOperation(with opUUID: UUID) -> YDBCloudCoreOperationStatus

  • Typically you are strongly discouraged from manually starting an operation. You should allow the pipeline to mange the queue, and only start operations when told to.

    However, there is one particular edge case in which is is unavoidable: background network tasks. If the app is relaunched, and you discover there are network tasks from a previous app session, you’ll obviously want to avoid starting the corresponding operation again. In this case, you should use this method to inform the pipeline that the operation is already started.

    Declaration

    Objective-C

    - (void)setStatusAsActiveForOperationWithUUID:(nonnull NSUUID *)opUUID;

    Swift

    func setStatusAsActiveForOperationWith(_ opUUID: UUID)

  • The PipelineDelegate may invoke this method to reset a failed operation. This gives control over the operation back to the pipeline, and it will dispatch it back to the PipelineDelegate again when ready.

    Declaration

    Objective-C

    - (void)setStatusAsPendingForOperationWithUUID:(nonnull NSUUID *)opUUID;

    Swift

    func setStatusAsPendingForOperationWith(_ opUUID: UUID)

Operation Hold

  • Returns the current hold for the operation (with the given context), or nil if there is no hold.

    Different context’s allow different parts of the system to operate in parallel. For example, if an operation requires several different subsystems to each complete an action, then each susbsystem can independently place a hold on the operation. Once all holds are lifted, the pipeline can dispatch the operation again.

    Declaration

    Objective-C

    - (nullable NSDate *)holdDateForOperationWithUUID:(nonnull NSUUID *)opUUID
                                          context:(nonnull NSString *)context;

    Swift

    func holdDateForOperation(with opUUID: UUID, context: String) -> Date?

  • And operation can be put on hold until a specified date.

    There are multiple uses for this. For example:

    • An operation may require various preparation tasks to complete before it can be started.
    • A failed operation may use a holdDate in conjunction with retry logic, such as exponential backoff.

    The operation won’t be started again until all associated holdDate’s have expired. You can pass a nil date to remove a hold on an operation (for a given context).

    Declaration

    Objective-C

    - (void)setHoldDate:(nullable NSDate *)date
    forOperationWithUUID:(nonnull NSUUID *)opUUID
                 context:(nonnull NSString *)context;

    Swift

    func setHold(_ date: Date?, forOperationWith opUUID: UUID, context: String)

  • Returns the latest hold date for the given operation.

    If there are no holdDates for the operation, returns nil. If there are 1 or more holdDates, returns the latest date.

    Declaration

    Objective-C

    - (nullable NSDate *)latestHoldDateForOperationWithUUID:
    (nonnull NSUUID *)opUUID;

    Swift

    func latestHoldDateForOperation(with opUUID: UUID) -> Date?

  • Returns a dictionary of all the hold dates associated with an operation.

    Declaration

    Objective-C

    - (nullable NSDictionary<NSString *, NSDate *> *)holdDatesForOperationWithUUID:
    (nonnull NSUUID *)opUUID;

    Swift

    func holdDatesForOperation(with opUUID: UUID) -> [String : Date]?

  • Returns a dictionary of all the hold dates associated with a particular context.

    Declaration

    Objective-C

    - (nullable NSDictionary<NSUUID *, NSDate *> *)holdDatesForContext:
    (nonnull NSString *)context;

    Swift

    func holdDates(forContext context: String) -> [UUID : Date]?

Suspend & Resume

  • Returns YES if the upload operation queue is suspended.

    See

    suspend

    See

    resume

    Declaration

    Objective-C

    @property (readonly, atomic) BOOL isSuspended;

    Swift

    var isSuspended: Bool { get }

  • Returns the current suspendCount. If the suspendCount is zero, that means isSuspended == NO; if the suspendCount is non-zero, that means isSuspended == YES;

    See

    suspend

    See

    resume

    Declaration

    Objective-C

    @property (readonly, atomic) NSUInteger suspendCount;

    Swift

    var suspendCount: UInt { get }

  • Increments the suspendCount. All calls to ‘suspend’ need to be matched with an equal number of calls to ‘resume’.

    @return The new suspend count. This will be 1 if the pipeline was previously active, and is now suspended due to this call. Otherwise it will be greater than one, meaning it was previously suspended, and you just incremented the suspend count.

    See

    resume

    See

    suspendCount

    Declaration

    Objective-C

    - (NSUInteger)suspend;

    Swift

    func suspend() -> UInt

  • This method operates the same as invoking the suspend method the given number of times. That is, it increments the suspend count by the given number.

    If you invoke this method with a zero parameter, it will simply return the current suspend count, without modifying it.

    See

    suspend

    See

    suspendCount

    Declaration

    Objective-C

    - (NSUInteger)suspendWithCount:(NSUInteger)suspendCountIncrement;

    Swift

    func suspend(withCount suspendCountIncrement: UInt) -> UInt

  • Decrements the suspendCount. All calls to ‘suspend’ need to be matched with an equal number of calls to ‘resume’.

    @return The current suspend count. This will be 0 if the extension was previously suspended, and is now resumed due to this call. Otherwise it will be greater than one, meaning it’s still suspended, and you just decremented the suspend count.

    See

    suspend

    See

    suspendCount

    Declaration

    Objective-C

    - (NSUInteger)resume;

    Swift

    func resume() -> UInt

Activity

  • A pipeline transitions to the ‘active’ state when:

    • There are 1 or more operations in ‘YDBCloudOperationStatus_Active’ mode.

    A pipeline transitions to the ‘inactive’ state when:

    • There are 0 operations in ‘YDBCloudOperationStatus_Active’ mode
    • AND (the pipeline is suspended OR there are no more operations)

    ^In other words, there may be situations in which there are zero active operations, due to something like a conflict resolution, however the pipeline is still considered active because it still has pending operations, and it hasn’t been suspended.

    Declaration

    Objective-C

    @property (readonly, atomic) BOOL isActive;

    Swift

    var isActive: Bool { get }