Document asynchronous APIs

Author: SavchenkoValeriy

Source/Swift/Channel+Hooks+Boilerplate.swift

@@ -85,6 +85,13 @@ class LazyHook5<
 }
 
 extension Channel {
+  /// Make a Swift callback out of an Emacs hook's name.
+  ///
+  /// This allows us to use Emacs hooks as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a name of a Lisp hook to turn into callback.
+  /// - Returns: a callback that if called, will eventually run the hook.
   public func hook(_ hook: String)
     -> () -> Void
   {
@@ -93,6 +100,13 @@ extension Channel {
         callback: LazyHook0(hook: hook), args: ())
     }
   }
+  /// Make a Swift callback out of an Emacs hook's name.
+  ///
+  /// This allows us to use Emacs hooks as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a name of a Lisp hook to turn into callback.
+  /// - Returns: a callback that if called, will eventually run the hook.
   public func hook<T: EmacsConvertible>(_ hook: String)
     -> (T) -> Void
   {
@@ -101,6 +115,13 @@ extension Channel {
         callback: LazyHook1<T>(hook: hook), args: arg)
     }
   }
+  /// Make a Swift callback out of an Emacs hook's name.
+  ///
+  /// This allows us to use Emacs hooks as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a name of a Lisp hook to turn into callback.
+  /// - Returns: a callback that if called, will eventually run the hook.
   public func hook<T1: EmacsConvertible, T2: EmacsConvertible>(
     _ hook: String
   ) -> (T1, T2) -> Void {
@@ -110,6 +131,13 @@ extension Channel {
         args: (arg1, arg2))
     }
   }
+  /// Make a Swift callback out of an Emacs hook's name.
+  ///
+  /// This allows us to use Emacs hooks as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a name of a Lisp hook to turn into callback.
+  /// - Returns: a callback that if called, will eventually run the hook.
   public func hook<
     T1: EmacsConvertible, T2: EmacsConvertible, T3: EmacsConvertible
   >(
@@ -121,6 +149,13 @@ extension Channel {
         args: (arg1, arg2, arg3))
     }
   }
+  /// Make a Swift callback out of an Emacs hook's name.
+  ///
+  /// This allows us to use Emacs hooks as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a name of a Lisp hook to turn into callback.
+  /// - Returns: a callback that if called, will eventually run the hook.
   public func hook<
     T1: EmacsConvertible, T2: EmacsConvertible, T3: EmacsConvertible,
     T4: EmacsConvertible
@@ -133,6 +168,13 @@ extension Channel {
         args: (arg1, arg2, arg3, arg4))
     }
   }
+  /// Make a Swift callback out of an Emacs hook's name.
+  ///
+  /// This allows us to use Emacs hooks as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a name of a Lisp hook to turn into callback.
+  /// - Returns: a callback that if called, will eventually run the hook.
   public func hook<
     T1: EmacsConvertible, T2: EmacsConvertible, T3: EmacsConvertible,
     T4: EmacsConvertible, T5: EmacsConvertible

Source/Swift/Channel+LispCallback+Boilerplate.swift

@@ -79,6 +79,13 @@ class LazyLispCallback5<
 }
 
 extension Channel {
+  /// Make a Swift callback out of an Emacs function.
+  ///
+  /// This allows us to use Emacs functions as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a Lisp function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback(_ function: EmacsValue)
     -> () -> Void
   {
@@ -87,6 +94,13 @@ extension Channel {
         callback: LazyLispCallback0(function: function), args: ())
     }
   }
+  /// Make a Swift callback out of an Emacs function.
+  ///
+  /// This allows us to use Emacs functions as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a Lisp function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<T: EmacsConvertible>(_ function: EmacsValue)
     -> (T) -> Void
   {
@@ -95,6 +109,13 @@ extension Channel {
         callback: LazyLispCallback1<T>(function: function), args: arg)
     }
   }
+  /// Make a Swift callback out of an Emacs function.
+  ///
+  /// This allows us to use Emacs functions as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a Lisp function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<T1: EmacsConvertible, T2: EmacsConvertible>(
     _ function: EmacsValue
   ) -> (T1, T2) -> Void {
@@ -104,6 +125,13 @@ extension Channel {
         args: (arg1, arg2))
     }
   }
+  /// Make a Swift callback out of an Emacs function.
+  ///
+  /// This allows us to use Emacs functions as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a Lisp function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<
     T1: EmacsConvertible, T2: EmacsConvertible, T3: EmacsConvertible
   >(
@@ -115,6 +143,13 @@ extension Channel {
         args: (arg1, arg2, arg3))
     }
   }
+  /// Make a Swift callback out of an Emacs function.
+  ///
+  /// This allows us to use Emacs functions as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a Lisp function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<
     T1: EmacsConvertible, T2: EmacsConvertible, T3: EmacsConvertible,
     T4: EmacsConvertible
@@ -127,6 +162,13 @@ extension Channel {
         args: (arg1, arg2, arg3, arg4))
     }
   }
+  /// Make a Swift callback out of an Emacs function.
+  ///
+  /// This allows us to use Emacs functions as callbacks in Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a Lisp function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<
     T1: EmacsConvertible, T2: EmacsConvertible, T3: EmacsConvertible,
     T4: EmacsConvertible, T5: EmacsConvertible

Source/Swift/Channel+SwiftCallback+Boilerplate.swift

@@ -69,6 +69,13 @@ class LazySwiftCallback5<T1, T2, T3, T4, T5>: AnyLazyCallback {
 }
 
 extension Channel {
+  /// Make a callback that doesn't require the environment from a closure that does.
+  ///
+  /// This allows us to contact Emacs as part of asynchronous callbacks from Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback(function: @escaping (Environment) throws -> Void)
     -> () -> Void
   {
@@ -77,6 +84,13 @@ extension Channel {
         callback: LazySwiftCallback0(function: function), args: ())
     }
   }
+  /// Make a callback that doesn't require the environment from a closure that does.
+  ///
+  /// This allows us to contact Emacs as part of asynchronous callbacks from Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<T>(function: @escaping (Environment, T) throws -> Void)
     -> (T) -> Void
   {
@@ -85,6 +99,13 @@ extension Channel {
         callback: LazySwiftCallback1(function: function), args: arg)
     }
   }
+  /// Make a callback that doesn't require the environment from a closure that does.
+  ///
+  /// This allows us to contact Emacs as part of asynchronous callbacks from Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<T1, T2>(
     function: @escaping (Environment, T1, T2) throws -> Void
   ) -> (T1, T2) -> Void {
@@ -93,6 +114,13 @@ extension Channel {
         callback: LazySwiftCallback2(function: function), args: (arg1, arg2))
     }
   }
+  /// Make a callback that doesn't require the environment from a closure that does.
+  ///
+  /// This allows us to contact Emacs as part of asynchronous callbacks from Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<T1, T2, T3>(
     function: @escaping (Environment, T1, T2, T3) throws -> Void
   ) -> (T1, T2, T3) -> Void {
@@ -102,6 +130,13 @@ extension Channel {
         args: (arg1, arg2, arg3))
     }
   }
+  /// Make a callback that doesn't require the environment from a closure that does.
+  ///
+  /// This allows us to contact Emacs as part of asynchronous callbacks from Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<T1, T2, T3, T4>(
     function: @escaping (Environment, T1, T2, T3, T4) throws -> Void
   ) -> (T1, T2, T3, T4) -> Void {
@@ -111,6 +146,13 @@ extension Channel {
         args: (arg1, arg2, arg3, arg4))
     }
   }
+  /// Make a callback that doesn't require the environment from a closure that does.
+  ///
+  /// This allows us to contact Emacs as part of asynchronous callbacks from Swift APIs.
+  /// Please, see <doc:AsyncCallbacks> for more details on that.
+  ///
+  /// - Parameter function: a function to turn into a callback.
+  /// - Returns: a callback that if called, will eventually call the given function.
   public func callback<T1, T2, T3, T4, T5>(
     function: @escaping (Environment, T1, T2, T3, T4, T5) throws -> Void
   ) -> (T1, T2, T3, T4, T5) -> Void {
@@ -121,6 +163,13 @@ extension Channel {
     }
   }
 
+  /// Execute the given closure with Emacs environment.
+  ///
+  /// This function allows us to asynchronously use environment
+  /// to execute code on the Emacs side whenever we have any
+  /// updates.
+  ///
+  /// - Parameter function: a callback to execute with Emacs environment
   public func withEnvironment(_ function: @escaping (Environment) throws -> Void) {
     register(callback: LazySwiftCallback0(function: function), args: ())
   }

Source/Swift/Documentation.docc/AsyncCallbacks.md

@@ -1,3 +1,92 @@
 # Asynchronous Callbacks
 
 Calling Lisp functions without an active Environment.
+
+## Overview
+
+As it was mentioned in <doc:Lifetimes>, ``Environment`` instances could not be stored and captured. Additionally, dynamic modules are not allowed to use given environments from a different thread they were given it on. This can be a problem if we want to use one of the rich Swift APIs to do some useful work for us. We do want to tell the Emacs side that the work was done, and pass in some results. ``Channel`` mechanism was designed specifically with this goal in mind and it provides multiple ways of passing data back into Lisp.
+
+## Creating a Channel
+
+In order to create a ``Channel``, you do need to have an active environment. Simply call ``Environment/openChannel(name:)`` with a name for that channel, and that's pretty much it. You are allowed to create multiple channels and use them simultaneously. Channel callbacks are serialized to be called in exactly the same order their Swift counter-parts got called in the first place. Because of this reason, it might be a good idea to have different channels for less frequent important callbacks and more frequent, but less important callbacks.
+
+## withEnvironment
+
+The easiest way of interacting with ``Environment`` using an open ``Channel`` is via ``Channel/withEnvironment(_:)``. This function allows you to execute some code with Emacs environment whenever we'll get it from Emacs.
+
+```swift
+// do some work
+channel.withEnvironment {
+  env throws in try env.funcall("message", with: "The work is done!")
+}
+// keep doing something else
+```
+
+It should be noted that the code from `// keep doing something else` will most likely get executed before before our message will appear in Emacs. For this reason, `withEnvironment` (and other callbacks) don't have return values.
+
+## callback
+
+In many cases, we want to adapt some asynchronous APIs to Lisp. Let's say we have a UI form that represents a text-field or something similar. When the user submits the form, a callback is called with the user-written text. We probably don't want to do anything with this text on the Swift side, but our module can pass it to the Lisp side. Of course, we can implement it using ``Channel/withEnvironment(_:)``:
+
+```swift
+form.onSubmit {
+  (text: String) in
+  channel.withEnvironment {
+    env throws in try env.funcall("lisp-on-submit", with: text)
+  }
+}
+```
+
+Instead of having to closures, we can use one of the `callback` methods.
+
+```swift
+form.onSubmit(channel.callback {
+  (env: Environment, text: String) throws in
+  try env.funcall("lisp-on-submit", with: text)
+})
+```
+
+This family of methods turns closures that have ``Environment`` as its first parameter into closures that don't. In our example, it's `((Environment, String) -> Void) -> (String) -> Void`.
+
+This way, we can write the code that would've been very similar to the code that doesn't need to communicate with Emacs in the first place. However, sometimes we don't even need to do anything else except for communicating with Lisp.
+
+Let's extend our previous example:
+
+```swift
+try env.defun("create-form") {
+  (onSubmit: PersistentEmacsValue) in
+  let form = new Form()
+  form.onSubmit(channel.callback {
+    (env: Environment, text: String) throws in
+    try env.funcall(onSubmit, with: text)
+  })
+  return form
+}
+```
+
+Here, we expose form creation to Lisp in its entirety, and allow users to create it when they want it and have a callback completely on the Lisp side. This code works, but feels a bit wordy. For this reason, ``Channel`` provides a family of methods also named `callback` that work with ``EmacsValue`` functions directly. Let's look at how we can rewrite our code first.
+
+```swift
+try env.defun("create-form") {
+  (onSubmit: PersistentEmacsValue) in
+  let form = new Form()
+  form.onSubmit(channel.callback(onSubmit))
+  return form
+}
+```
+
+That's it, we turned `onSubmit` Lisp function into a Swift closure: `(String) -> Void`. You can use this formula with all kinds of closure types, ``Channel`` will create a Swift closure exactly of type that's expected by the API. Of course, since we call into a Lisp function, it means that all arguments should be ``EmacsConvertible`` (see <doc:TypeConversions>).
+
+## hooks
+
+Emacs Lisp has a different way of notifying some code of system-wide events, - hooks. In some cases, it would be the most appropriate tool to use for designing our module's API. ``Channel`` also provides a family of `hook` methods that you can use this way:
+
+```swift
+try env.defun("create-form") {
+  let form = new Form()
+  form.onSubmit(channel.hook("form-submit-hooks"))
+  return form
+}
+```
+
+Essentially, it does the same thing as the `callback` method in the earlier snippet, but it runs a hook instead.