SafeLink

public class SafeLink<B> : SafeChainable

SafeLink is a representation of a Link which is guaranteed to non-erroring. The interface of SafeLink is a proper subset of the interface to Link. All functions in Link which are capable of introducing errors into the process chain are omitted from the interface of SafeLink. To transition from a non-erroring chain to an erroring chain use setErrorHandler: which returns a full Link.

  • Creates a new SafeLink which accesses a keypath starting at B and ending at type C and appends the link to the execution list of this Link

    See more

    Declaration

    Swift

    public func chain<C>(file: StaticString = #file, line: UInt = #line, functionDescription: String? = nil, _ keyPath: KeyPath<B,C>) -> Link<C>
  • Set the execution queue for all descendant links. N.B. this does not change the execution queue for the receiver’s function. Example

    HoneyBee.start(on: .main) { root in
       root.setErrorHandlder(handleError)
           .chain(funcA)
           .setQueue(.global())
           .chain(funcB)
    }
    

    In the preceding example, funcA will run on DispatchQueue.main and funcB will run on DispatchQueue.global()

    Declaration

    Swift

    public func setBlockPerformer(_ blockPerformer: AsyncBlockPerformer) -> SafeLink<B>

    Parameters

    queue

    the new DispatchQueue for child links

    Return Value

    the receiver

  • insert inserts a value of any type into the chain data flow.

    See more

    Declaration

    Swift

    public func insert<C>(file: StaticString = #file, line: UInt = #line, _ c: C) -> SafeLink<C>

    Parameters

    c

    Any value

    Return Value

    a SafeLink whose child links will receive c as their function argument.

  • drop ignores drops the inbound value and returns a SafeLink whose value is Void

    Declaration

    Swift

    public func drop(file: StaticString = #file, line: UInt = #line) -> SafeLink<Void>

    Return Value

    a SafeLink whose child links will receive Void as their function argument.

  • tunnel defines a subchain with whose value is ultimately discarded. The links within the tunnel subchain run sequentially before the link which is the return value of tunnel. tunnel returns a SafeLink whose execution result B is the result the receiver link. Thus the value B hides or goes under ground while the subchain processes and pops back up when it is completed. For example:

     .insert(8)
     .tunnel { link in
        link.chain(intToString) //convert int to string
     }
     .chain(multiplyInt)
    

    In the example above insert results in an Int into the chain and that int is passed along to intToString which transform the value into a String. After the tunnel context has finished, the original value 8 (an Int) is passed to multiplyInt

    See more

    Declaration

    Swift

    public func tunnel<R>(file: StaticString = #file, line: UInt = #line, _ defineBlock: (SafeLink<B>) -> SafeLink<R>) -> SafeLink<B>

    Parameters

    defineBlock

    a block which creates a subchain to be limited.

    Return Value

    a SafeLink whose execution result R is discarded.

  • Yields self to a new definition block. Within the block the caller may invoke chaining methods on block multiple times, thus achieving parallel chains. Example:

    link.branch { stem in
      stem.chain(func1)
          .chain(func2)
    
      stem.chain(func3)
          .chain(func4)
    }
    

    In the preceding example, when link is executed it will start the links containing func1 and func3 in parallel. func2 will execute when func1 is finished. Likewise func4 will execute when func3 is finished.

    Declaration

    Swift

    public func branch(_ defineBlock: (SafeLink<B>) -> Void)

    Parameters

    defineBlock

    the block to which this SafeLink yields itself.

  • Yields self to a new definition block. Within the block the caller may invoke chaining methods on block multiple times, thus achieving parallel chains. Example:

    link.branch { stem in
      let a = stem.chain(func1)
                  .chain(func2)
    
      let b = stem.chain(func3)
                  .chain(func4)
    
      return (a + b) // operator for .conjoin
               .chain(combine)
    }
    

    In the preceding example, when link is executed it will start the links containing func1 and func3 in parallel. func2 will execute when func1 is finished. Likewise func4 will execute when func3 is finished.

    See more

    Declaration

    Swift

    public func branch<C>(_ defineBlock: (SafeLink<B>) -> SafeLink<C>) -> SafeLink<C>

    Parameters

    defineBlock

    the block to which this SafeLink yields itself.

    Return Value

    The link which is returned from defineBlock

  • conjoin is a compliment to branch. Within the context of a branch it is natural and expected to create parallel execution chains. If the process definition wishes at some point to combine the results of these execution chains, then conjoin should be used. conjoin returns a SafeLink which waits for both the receiver and the argument SafeLinks created results. Those results are combined into a tuple (B,C) which is passed to the child links of the returned SafeLink

    See more

    Declaration

    Swift

    public func conjoin<C>(_ other: SafeLink<C>) -> SafeLink<(B,C)>

    Parameters

    other

    the SafeLink to join with

    Return Value

    A SafeLink which combines the receiver and the arguments results.

  • conjoin is a compliment to branch. Within the context of a branch it is natural and expected to create parallel execution chains. If the process definition wishes at some point to combine the results of these execution chains, then conjoin should be used. conjoin returns a SafeLink which waits for both the receiver and the argument SafeLinks created results. Those results are combined into a tuple (X, Y, C) which is passed to the child links of the returned SafeLink

    See more

    Declaration

    Swift

    public func conjoin<X,Y,C>(other: SafeLink<C>) -> SafeLink<(X,Y,C)> where B == (X,Y)

    Parameters

    other

    the SafeLink to join with

    Return Value

    A SafeLink which combines the receiver and the arguments results.

  • conjoin is a compliment to branch. Within the context of a branch it is natural and expected to create parallel execution chains. If the process definition wishes at some point to combine the results of these execution chains, then conjoin should be used. conjoin returns a SafeLink which waits for both the receiver and the argument SafeLinks created results. Those results are combined into a tuple (X, Y, Z, C) which is passed to the child links of the returned SafeLink

    See more

    Declaration

    Swift

    public func conjoin<X,Y,Z,C>(other: SafeLink<C>) -> SafeLink<(X,Y,Z,C)> where B == (X,Y,Z)

    Parameters

    other

    the SafeLink to join with

    Return Value

    A SafeLink which combines the receiver and the arguments results.

  • operator syntax for conjoin function

    See more

    Declaration

    Swift

    public static func +<C>(lhs: SafeLink<B>, rhs: SafeLink<C>) -> SafeLink<(B,C)>
  • operator syntax for conjoin function

    See more

    Declaration

    Swift

    public static func +<X,Y,C>(lhs: SafeLink<B>, rhs: SafeLink<C>) -> SafeLink<(X,Y,C)> where B == (X,Y)
  • operator syntax for conjoin function

    See more

    Declaration

    Swift

    public static func +<X,Y,Z,C>(lhs: SafeLink<B>, rhs: SafeLink<C>) -> SafeLink<(X,Y,Z,C)> where B == (X,Y,Z)
  • operator syntax for join left behavior

    See more

    Declaration

    Swift

    public static func <+<C>(lhs: SafeLink<B>, rhs: SafeLink<C>) -> SafeLink<B>

    Parameters

    lhs

    SafeLink whose value to propagate

    rhs

    SafeLink whose value to drop

    Return Value

    a SafeLink which contains the value of the left-hand SafeLink

  • operator syntax for join right behavior

    See more

    Declaration

    Swift

    public static func +><C>(lhs: SafeLink<B>, rhs: SafeLink<C>) -> SafeLink<C>

    Parameters

    lhs

    SafeLink whose value to drop

    rhs

    SafeLink whose value to propagate

    Return Value

    a SafeLink which contains the value of the left-hand SafeLink

  • When B is an Optional you may call optionally. The supplied define block creates a subchain which will be run if the Optional value is non-nil. The SafeLink given to the define block yields a non-optional value of B.WrappedType to its child links This function returns a SafeLink with a void result value, because the subchain defined by optionally will not be executed if B is nil.

    See more

    Declaration

    Swift

    public func optionally<X>(_ defineBlock: @escaping (SafeLink<B.WrappedType>) -> SafeLink<X>) -> SafeLink<B>

    Parameters

    defineBlock

    a block which creates a subchain to run if B is non-nil

    Return Value

    a SafeLink with a void value type.

  • limit defines a subchain with special runtime protections. The links within the limit subchain are guaranteed to have at most maxParallel parallel executions. limit is particularly useful in the context of a fully parallel process when part of the process must access a limited resource pool such as CPU execution contexts or network resources. This method returns a SafeLink whose execution result J is the result of the final link of the subchain. This permits the chain to proceed naturally after limit. For example:

     .limit(5) { link in
        link.chain(resourceLimitedIntGenerator)
    }
    .chain(multiplyInt)
    

    In the example above resourceLimitedIntGenerator results in an Int and that int is passed along to multipyInt after the limit context has finished.

    See more

    Declaration

    Swift

    public func limit<J>(_ maxParallel: Int, _ defineBlock: (SafeLink<B>) -> SafeLink<J>) -> SafeLink<J>

    Parameters

    maxParallel

    the maximum number of parallel executions permitted for the subchains defined by defineBlock

    defineBlock

    a block which creates a subchain to be limited.

    Return Value

    a SafeLink whose execution result J is the result of the final link of the subchain.

  • limit defines a subchain with special runtime protections. The links within the limit subchain are guaranteed to have at most maxParallel parallel executions. limit is particularly useful in the context of a fully parallel process when part of the process must access a limited resource pool such as CPU execution contexts or network resources.

    Declaration

    Swift

    public func limit(_ maxParallel: Int, _ defineBlock: (SafeLink<B>) -> Void) -> Void

    Parameters

    maxParallel

    the maximum number of parallel executions permitted for the subchains defined by defineBlock

    defineBlock

    a block which creates a subchain to be limited.

  • When the inbound type is a Collection, you may call map to asynchronously map over the elements of B in parallel, transforming them with transform subchain.

    See more

    Declaration

    Swift

    public func map<C>(limit: Int? = nil, acceptableFailure: FailureRate = .none, _ transform: @escaping (SafeLink<B.Iterator.Element>) -> SafeLink<C>) -> SafeLink<[C]>

    Parameters

    transform

    the transformation subchain defining block which converts B.Iterator.Element to C

    Return Value

    a SafeLink which will yield an array of Cs to it’s child links.

  • When the inbound type is a Collection, you may call filter to asynchronously filter the elements of B in parallel, using filter subchain

    Declaration

    Swift

    public func filter(limit: Int? = nil, acceptableFailure: FailureRate = .none, _ filter: @escaping (SafeLink<B.Iterator.Element>) -> SafeLink<Bool>) -> SafeLink<[B.Iterator.Element]>

    Parameters

    filter

    the filter subchain which produces a Bool

    Return Value

    a SafeLink which will yield to it’s child links an array containing those B.Iterator.Elements which filter approved.

  • When the inbound type is a Collection, you may call each Each accepts a define block which creates a subchain which will be invoked once per element of the sequence. The SafeLink which is given as argument to the define block will pass to its child links the element of the sequence which is currently being processed.

    Declaration

    Swift

    public func each(limit: Int? = nil, acceptableFailure: FailureRate = .none, _ defineBlock: @escaping (SafeLink<B.Element>) -> Void) -> SafeLink<[B.Element]>

    Parameters

    defineBlock

    a block which creates a subchain for each element of the Collection

    Return Value

    a SafeLink which will pass the nonfailing elements of B to its child links

  • When the inbound type is a Collection, you may call reduce Reduce accepts a define block which creates a subchain which will be executed sequentially, once per element of the sequence. The result of each successive execution of the subchain will be forwarded to the next pass of the subchain. The result of the final execution of the subchain will be forwarded to the returned link.

    See more

    Declaration

    Swift

    public func reduce<T>(with t: T, acceptableFailure: FailureRate = .none, _ defineBlock: @escaping (SafeLink<(T,B.Element)>) -> SafeLink<T>) -> SafeLink<T>

    Return Value

    a SafeLink which will pass the result of the reduce to its child links.

  • When the inbound type is a Collection, you may call reduce Reduce accepts a define block which creates a subchain which will be executed in parallel, with up to N/2 other subchains. Each subchain combines two B.Elements into one B.Element. The result of each combination is again combined until a single value remains. This value is forwarded to the returned link.

    Declaration

    Swift

    public func reduce(_ defineBlock: @escaping (SafeLink<(B.Element,B.Element)>) -> SafeLink<B.Element>) -> SafeLink<B.Element>

    Parameters

    defineBlock

    a block which creates a subchain to combined two elements of the Collection

    Return Value

    a SafeLink which will pass the final combined result of the reduce to its child links.

  • Set the completion handling function for the recipe. The completion handler will be invoked exactly one time. The argument will either be the first error in the recpie or if the recipe does not error, the completion handler will be invoked with a nil argument once after the entire recipe has completed.

    Declaration

    Swift

    public func setCompletionHandler(_ completionHandler: @escaping (Error?) -> Void ) -> Link<B>

    Parameters

    completionHandler

    a function which takes an optional error.

    Return Value

    A Link which has the completion handler installed.

  • Set the completion handling function for the recipe. The completion handler will be invoked exactly one time. The argument will either be the first error in the recpie or if the recipe does not error, the completion handler will be invoked with a nil argument once after the entire recipe has completed.

    Declaration

    Swift

    public func setCompletionHandler(_ completionHandler: @escaping (ErrorContext?) -> Void ) -> Link<B>

    Parameters

    completionHandler

    a function which takes an optional ErrorContext. The context contains all available debug information on the erroring function, including the error itself.

    Return Value

    A Link which has the completion handler installed.