// Example: Making an asynchronous function be synchronous 
let (data, response, error) = <<-{ URLSession.shared.dataTask(url, completionHandler: $0).resume() }

// API we're given:
func findClosestPokemon(within: Double,
             completionHandler: (pokemon: Pokemon?, error: NSError?) -> Void)

func countPokeballs(completionHandler: (number: Int?, error: NSError?) -> Void)

func throwPokeballAt(pokemon: Pokemon,
           completionHandler: (success: Bool, error: NSError?) -> Void)

// Utility we want:
func throwAtClosestPokemon(within: Double,
                completionHandler: (success: Bool, pokemon: Pokemon?, error: NSError?) -> Void)

// The old way...
func throwAtClosestPokemon(within: Double,
                completionHandler: (success: Bool, pokemon: Pokemon?, error: NSError?) -> Void) {
    // Step 1
    findClosestPokemon(within: within) { pokemon, error in
        guard let p = pokemon where error == nil else {
            DispatchQueue.main.async {
                completionHandler(success: false, pokemon: nil, error: error)
            }
            return
        }

        // Step 2
        countPokeballs { number, error in
            guard let n = number where error == nil else {
                DispatchQueue.main.async {
                    completionHandler(success: false, pokemon: nil, error: error)
                }
                return
            }

            // Step 3
            throwPokeballAt(pokemon: p) { success, error in
                DispatchQueue.main.async {
                    completionHandler(success: success, error: error)
                }
            }
        }
    }
}

// The new way...
func throwAtClosestPokemon(within: Double,
                completionHandler: (success: Bool, pokemon: Pokemon?, error: NSError?) -> Void) {

    // Run everything inside a specified async queue, or DispatchQueue.global()
    myQueue.async {

        // Step 1
        let (pokemon, error) = <<+{ findClosestPokemon(within: within, completionHandler: $0) }
        guard let p = pokemon where error == nil else {
            return completionHandler +>> (success: false, error: error)
        }

        // Step 2
        let (number, error2) = <<+{ countPokeballs($0) }
        guard let n = number where error2 == nil else {
            return completionHandler +>> (success: false, error: error2)
        }

        // Step 3
        let (success, error3) = <<+{ throwPokeballAt(pokemon: p, completionHandler: $0) }
        completionHandler +>> (success: success, error: error3)
    }
}

func getAlbum(named: String, handler: (album: PhotoAlbum?, error: NSError?) -> Void)
func saveUser(completionHandler: (success: Bool) -> Void)
func verifyUser(name: String, password: String, completion: (valid: Bool) -> Void)

// Typical use of a function would look like:
getAlbum("pics") { photo, error in
    // ...
}

// <<+ will execute getAlbum on the main queue
let (album, error) = <<+{ getAlbum("pics", handler: $0) }

// <<~ will execute saveUser on the global concurrent background queue
let success        = <<~{ saveUser($0) }

// <<- will execute verifyUser immediately in the current queue (note that the
//     current thread will wait for the completion handler to be called before
//     returning the final value.)
let valid          = <<-{ verifyUser("myname", password: "mypass", completion: $0) }

// You can also specify *any* queue you want.  Here saveUser is called on myQueue.
let myQueue        = dispatch_queue_create("myQueue", nil)
let valid          = <<~myQueue ~~~ { saveUser($0) }

dispatch_async(someQueue) {
    completionHandler(..)
}

func syncReturnsVoid() { }
func syncReturnsParam(p: Int) -> Int { return p+1 }
func syncReturnsParamTuple(p: Int) -> (Int, String) { return (p+1, "\(p+1)") }

dispatch_async(someQueue) {

    // syncReturnsVoid() is called on the main thread
    syncReturnsVoid +>> ()

    // syncReturnsParam(p: 3) is called on the main thread
    // Note in this case the return value is ignored!
    syncReturnsParam +>> (p: 3)

    // syncReturnsVoid() is called on the global concurrent background queue
    syncReturnsVoid ~>> ()

    // syncReturnsParam(p: 3) is called on the global concurrent background queue
    // Note in this case the return value is ignored!
    syncReturnsParam ~>> (p: 3)

    let otherQueue = dispatch_queue_create("otherQueue", nil)

    // syncReturnsVoid() is called on otherQueue
    syncReturnsVoid ~>> otherQueue ~>> ()

    // syncReturnsParam(p: 3) is called on otherQueue
    // Note in this case the return value is ignored!
    syncReturnsParam ~>> otherQueue ~>> (p: 3)
}

dispatch_async(someQueue) {    
    let otherQueue = dispatch_queue_create("otherQueue", nil)

    // The following three lines are equivalent
    syncReturnsParam~>>.on(otherQueue).async(p: 3)
    syncReturnsParam~>>otherQueue~>>(p: 3)
    syncReturnsParam ~>> otherQueue ~>> (p: 3)
}

dispatch_async(someQueue) {

    // syncReturnsParam(p: 3) is called on the main thread
    // Its response is also handled on the main thread
    syncReturnsParam +>> (p: 3) +>> { i in print(i) } // prints 4

    // syncReturnsParam(p: 3) is called on the main thread
    // Its response is handled on the global concurrent background queue
    // Note the positions and difference between +>> and ~>>
    syncReturnsParam +>> (p: 3) ~>> { i in print(i) } // prints 4

    // syncReturnsParamTuple(p: 3) is called on the global concurrent background queue
    // Its response is handled on an instantiated queue
    syncReturnsParamTuple ~>> (p: 3) ~>> otherQueue ~>> { iInt, iStr in print(pInt) }

    // Using the more functional style
    syncReturnsParam~>>.on(otherQueue).async(p: 3) +>> { i in print(i) }    
}

func myTest(param: Int, completionHandler: (Int -> Int)? = nil) {

    // These will cause a compiler error because the handler is optional:
    completionHandler +>> (param)
    completionHandler+>>.async(param) +>> { i in print(i) }

    // Instead use these:
    completionHandler ?+>> (param)
    completionHandler?~>>.async(param)

    // For anything past the initial function, use normal operators:
    //     (+>> instead of ?+>>) --v
    completionHandler ?+>> (param) +>> { i in print(i) }

}

/// LibDispatch:
func asyncAfter(deadline: DispatchTime,
                     qos: DispatchQoS = default,
                   flags: DispatchWorkItemFlags = default,
                 execute: () -> Void)

// Brisk allows you to specify time/intervals as a Double instead of DispatchTime.
// It also allows you to capture the timer used to dispatch the block, in case
// you want to cancel it.
func async(after seconds: Double,
                  leeway: QuickDispatchTimeInterval? = nil,
                     qos: DispatchQoS = .default,
                   flags: DispatchWorkItemFlags = [],
           execute block: @escaping () -> Void) -> DispatchSourceTimer

// LibDispatch Requires:
let timer = DispatchSource.makeTimerSource(flags: ..., queue: ...)
timer.setEventHandler(qos: ..., flags: ..., handler: ...)
timer.scheduleRepeating(deadline: ..., interval: ..., leeway: ...)
timer.resume()

// Brisk allows you to schedule timers in one function, and passes the timer
// into the block so it can be canceled based on logic inside or outside the handler.
func async(every interval: Double,
               startingIn: Double? = nil,
               startingAt: NSDate? = nil,
                   leeway: QuickDispatchTimeInterval? = nil,
                      qos: DispatchQoS = .default,
                    flags: DispatchWorkItemFlags = [],
            execute block: @escaping (_ tmr: DispatchSourceTimer) -> Void) -> DispatchSourceTimer

func once(operationId: String,
       after interval: Double? = nil,
              at date: NSDate? = nil,
               leeway: QuickDispatchTimeInterval? = nil,
                  qos: DispatchQoS = .default,
                flags: DispatchWorkItemFlags = [],
        execute block: @escaping () -> Void) -> DispatchSourceTimer

dispatch_main_async {
    // Block runs on the main queue
}

dispatch_main_sync {
    // Block runs on the main queue; this function does not return until
    // the block completes.
}

dispatch_bg_async {
    // Block runs on the global concurrent background queue
}

dispatch_async("myNewQueue") {
    // Block runs on a brisk-created serial queue with the specified string ID.
    // Calling this function multiple times with the same string will reuse the
    // named queue.  Useful for dynamic throw-away serial queues.
}

dispatch_main_after(2.0) {
dispatch_after(2.0, myQueue) {
    // Block is called on specified queue after specified number of seconds using
    // a loose leeway (+/- 0.1 seconds).
}

dispatch_main_after_exactly(2.0) {
dispatch_after_exactly(2.0, myQueue) {
    // Block is called on specified queue after specified number of seconds using
    // as tight a timer leeway as possible.  Useful for animation timing but
    // uses more battery power.
}

dispatch_main_every(2.0) { timer in
dispatch_every(2.0, myQueue) { timer in
dispatch_main_every_exact(2.0) { timer in
dispatch_every_exact(2.0, myQueue) { timer in
    // Block is run on specified thread every N seconds.
    // Stop the timer with:
    dispatch_source_cancel(timer)
}

dispatch_main_once_after(2.0, "myOperationId") {
dispatch_once_after(2.0, myQueue, "myOperationId") {
    // Block runs after specified time on specified queue.  The block is
    // only executed ONCE -- repeat calls to this function with the same
    // operation ID will reset its internal timer instead of calling the
    // block again.  Useful for calling a completion block after several
    // disparate asynchronous methods (e.g. saving the database to disk
    // after downloading multiple records on separate threads.)
}

dispatch_each(myArray, myQueue) { element in
    // Each element in the array has this block called with it as a parameter.
    // Should be used on a concurrent queue.
}