document actor class import (#1998)

document actor class import

Author: crusso

doc/modules/language-guide/pages/language-manual.adoc

@@ -382,18 +382,29 @@ An import introduces a resource named '<id>?' referring to a local source module
 The syntax of a _library_ (that can be referenced in an import) is as follows:
 
 ```bnf
-<lib> ::=                                        library
-    <imp>;* module <id>? =? { <dec-field>;* }
+<lib> ::=                                                                                       library
+    <imp>;* module <id>? <obj-body>                                                               module
+    <imp>;* <shared-pat>? actor class <id> <typ-params>? <pat> (: <typ>)? <class-body>            actor class
 ```
 
-A library `<lib>` is a sequence of imports `<imp>;*` followed by a named or anonymous (module) declaration `module <id>? =? { <dec-field>;* }`.
+A library `<lib>` is a sequence of imports `<imp>;*` followed by:
 
-Libraries stored in {ext} files may be referenced by `import`s.
+* a named or anonymous (module) declaration; or
+* a named actor class declaration.
 
-The name `<id>?` is only significant within the library and does not determine the name of the library when imported.
+Libraries stored in {ext} files may be referenced by `import` declarations.
+
+In a module library, the optional name `<id>?` is only significant within the library and does not determine the name of the library when imported.
 Instead, the imported name of a library is determined by the `import` declaration, giving clients of the library the freedom to
 choose library names (e.g. to avoid clashes).
 
+An actor class library, because it defines both a type constructor and a function with name `<id>`, is imported as a module defining both a type and a function named `<id>`.
+The name `<id>` is mandatory and cannot be omitted.
+The imported actor class constructor is asynchronous, with return type `async T`. Here `T` is the inferred or supplied type of the class body.
+Because actor construction is asynchronous, an instance of an imported actor class can only be created in an asynchronous context
+(i.e. in the body of a (non-`query`) `shared` function or `async` expression).
+
+
 [[syntax-decls]]
 === Declaration syntax
 
@@ -405,10 +416,17 @@ The syntax of a _declaration_ is as follows:
   ignore <exp>                                                                           ignore
   let <pat> = <exp>                                                                      immutable
   var <id> (: <typ>)? = <exp>                                                            mutable
-  <sort> <id>? =? { <dec-field>;* }                                                      object
+  <sort> <id>? =? <obj-body>                                                             object
   <shared-pat>? func <id>? <typ-params>? <pat> (: <typ>)? =? <exp>                       function
   type <id> <typ-params>? = <typ>                                                        type
-  <shared-pat>? <sort>? class <id> <typ-params>? <pat> (: <typ>)? =? { <exp-field>;* }   class
+  <shared-pat>? <sort>? class <id>? <typ-params>? <pat> (: <typ>)? <class-body>          class
+
+<obj-body> ::=           object body
+   { <dec-field>;* }       field declarations
+
+<class-body> ::=         class body
+    = <id>? <obj-body>     object body, optionally binding <id> to _this_ instance
+    <obj-body>             object body
 ```
 
 The syntax of a shared function qualifier with call-context pattern is as follows:
@@ -496,7 +514,7 @@ The syntax of an _expression_ is as follows:
   try <exp> catch <pat> <exp>                    catch an error (only in async)
   assert <exp>                                   assertion
   <exp> : <typ>                                  type annotation
-  dec                                            declaration
+  <dec>                                          declaration
   debug <exp>                                    debug expression
   actor <canister-id-exp>                        actor reference
   ( <exp> )                                      parentheses
@@ -931,7 +949,7 @@ A type `T` is well-formed only if (recursively) its constituent types are well-f
 * if `T` is `async U` then `U` is shared, and
 * if `T` is `shared query? U -> V`, `U` is shared and
   `V == ()` or `V == async W'` with `W` shared, and
-* if `T` is `C<T0, ..., TN>` where:
+* if `T` is `C<T0, ..., Tn>` where:
 ** a declaration `type C<X0 <: U0, Xn <: Un>  = ...` is in scope, and
 ** `Ti <: Ui[ T0/X0, ..., Tn/Xn ]`, for each `0 \<= i \<= n`.
 * if `T` is `actor { ... }` then all fields in `...` are immutable and have `shared` function type.
@@ -985,15 +1003,15 @@ Two types `T`, `U` are related by subtyping, written `T <: U`, whenever, one of
   `U` is a function type `<shared>? <X0 <: W0, ..., Xn <: Wn> U1 -> U2` and
 ** `T` and `U` are either both equivalently `<shared>?`, and
 ** assuming constraints `X0 <: W0, ..., Xn <: Wn` then
-*** for all `i`, `Wi <: Vi`, and
+*** for all `i`, `Wi == Vi`, and
 *** `U1 <: T1`, and
 *** `T2 <: U2`.
 +
 (That is, function type `T` is a subtype of function type `U` if they have same `<shared>?` qualification, they have the same type parameters (modulo renaming) and assuming the bounds in `U`,
  every bound in `T` supertypes the corresponding parameter bound in `U` (contra-variance), the domain of `T` supertypes the domain of `U` (contra-variance) and the range of `T` subtypes
  the range of `U` (co-variance).)
 +
-* `T` (respectively `U`) is a constructed type `C<V0,...VN>` that is equal, by definition of type constructor `C`,  to `W`, and `W <: U` (respectively `U <: W`).
+* `T` (respectively `U`) is a constructed type `C<V0, ..., Vn>` that is equal, by definition of type constructor `C`,  to `W`, and `W <: U` (respectively `U <: W`).
 
 * For some type `V`, `T <: V` and `V <: U` (_transitivity_).
 
@@ -1061,18 +1079,59 @@ A program evaluates by (transitively) evaluating the imports, binding their valu
 [[libraries]]
 === Libraries
 
-A library `<imp>;* module <id>? =? { <dec-field>;* }` is a sequence of imports `<import>;*` followed by a single module declaration.
+Restrictions on the syntactic form of modules means that libraries can have no side-effects.
+
+The imports of a library are local and not re-exported in its interface.
+
+Multiple imports of the same library can be safely deduplicated without loss of side-effects.
+
+==== Module libraries
+
+A library `<imp>;* module <id>? <obj-body>` is a sequence of imports `<import>;*` followed by a single module declaration.
 
 A library has module type `T` provided
 
-* `module <id>? =? { <dec-field>;* }` has (module) type `T` under the static environment induced by the imports in `<import>;*`.
+* `module <id>? <obj-body>` has (module) type `T` under the static environment induced by the imports in `<import>;*`.
 
-The imports of a library are local and not re-exported in its interface.
+A module library evaluates by (transitively) evaluating its imports, binding their values to the identifiers in `<imp>;*` and then evaluating `module <id>? <obj-body>`.
 
-A library evaluates by (transitively) evaluating its imports, binding their values to the identifiers in `<imp>;*` and then evaluating the sequence of declarations in `<dec>;*`.
+==== Actor class libraries
 
-Restrictions on the syntactic form of modules means that libraries can have no side-effects.
-Multiple imports of the same library can be safely deduplicated without loss of side-effects.
+////
+This ugly asyncification of actor class imports below will go away once we change actor class definitions to be asynchronous. This is a temporary kludge.
+////
+
+The actor class library `<imp>;* <dec>` where `<dec>` is of the form  `<shared-pat>? actor class <id> <typ-params>? <pat> (: <typ>)? <class-body>` has type:
+
+```
+  module {
+    type <id> = T;
+    <id> : (U1,...,Un) -> async T // asynchronous!
+  }
+```
+
+provided that:
+
+* the actor class declaration `<dec>` has function type `(U1, ..., Un) -> T` under the static environment induced by the imports in `<import>;*`.
+
+Notice that the imported type of the function `<id>` is the *asynchronous* version of its declared type.
+
+An actor class library evaluates by (transitively) evaluating its imports, binding their values to the identifiers in `<imp>;*`, and evaluating the (derived) module:
+
+```
+  module {
+    public type <id> = T;
+    public func <id>(a1 : U1, ..., an : Un) : async T { // asynchronous!
+      (<dec>)(a1, ..., an)
+    }
+  }
+```
+
+The imported module contains an asynchronous implementation of function `<id>`.
+
+On the Internet Computer, calling `await <id>(<exp1>, ..., <expn>)`, installs a fresh instance of the actor class as an isolated IC canister, passing the values of `<exp1>`, ..., `<expn>`
+as installation arguments, and returns a reference to a (remote) actor of type `T`.
+Installation is (necessarily) asynchronous.
 
 [[imports]]
 === Imports and Urls
@@ -1163,7 +1222,7 @@ During an upgrade, a trap occuring in the implicit call to `preupgrade()` or `po
 [[decl-seq]]
 === Sequence of declarations
 
-A sequence of declarations `<dec>;*` occurring in a block, a program or the `exp-field;*` sequence of an object declaration has type `T`
+A sequence of declarations `<dec>;*` occurring in a block, a program or embedded in the `<dec-field>;*` sequence of an object body has type `T`
 provided:
 
 * `<dec>;*` is empty and `T == ()`; or
@@ -1345,13 +1404,13 @@ In scope of the declaration  `type C < X0<:T0>, ..., Xn <: Tn > = U`, any  well-
 [[decl-obj]]
 === Object declaration
 
-Declaration `<sort> <id>? =? { <exp-field>;* }` declares an object with optional identifier `<id>` and zero or more fields `<exp-field>;*`.
+Declaration `<sort> <id>? <obj-body>`, where `<obj_body>` is of the form `=? { <dec-field>;* }`, declares an object with optional identifier `<id>` and zero or more fields `<dec-field>;*`.
 Fields can be declared with `public` or `private` visibility; if the visibility is omitted, it defaults to `private`.
 
 The qualifier `<sort>` (one of `actor`, `module` or `object`) specifies the *sort* of the object's type. The sort imposes restrictions on the types of the public object fields.
 
 Let `T = sort { [var0] id0 : T0, ... , [varn] idn : T0 }` denote the type of the object.
-Let `<dec>;*` be the sequence of declarations in `<exp_field>;*`.
+Let `<dec>;*` be the sequence of declarations embedded in `<dec-field>;*`.
 The object declaration has type `T` provided that:
 
 1. type `T` is well-formed for sort `sort`, and
@@ -1395,20 +1454,25 @@ Named function definitions are recursive.
 [[decl-class]]
 === Class declaration
 
-The declaration `<shared-pat>? <sort>? class <id> <typ-params>? <pat> (: <typ>)? =? <id_this>? { <exp-field>;* }` is sugar for pair of a type and function declaration:
+////
+TODO: revise once actor class declaration async
+////
+
+The _class_ declaration `<shared-pat>? <sort>? class <id>? <typ-params>? <pat> (: <typ>)? <class-body>` is sugar for pair of a type and function declaration:
 
 ```bnf
-<shared-pat>? <sort>? class <id> <typ-params>? <pat> (: <typ>)? =? <id_this>? { <dec-field>;* } :=
+<shared-pat>? <sort>? class <id> <typ-params>? <pat> (: <typ>)? <class-body> :=
   type <id> <typ-params> = <sort> { <typ-field>;* };
-  <shared-pat>? func <id> <typ-params>? <pat> : <id> <typ-args>  = <sort> <id_this>? { <dec-field>;* }
+  <shared-pat>? func <id> <typ-params>? <pat> : <id> <typ-args> = <sort> <id_this>? <obj-body>
 ```
 
 where:
 
 * `<shared-pat>?`, when present, requires `<sort>` == `actor`, and provides access to the `caller` of an `actor` constructor, and
 * `<typ-args>?` is the sequence of type identifiers bound by `<typ-params>?` (if any), and
 * `<typ-field>;*` is the set of public field types inferred from `<dec-field>;*`.
-* `<id_this>?` is the optional `this` parameter of the object instance.
+* `<obj-body>` is the object body of `<class-body>`.
+* `<id_this>?` is the optional _this_ (a.k.a _self_), parameter of `<class-body>`.
 
 Note `<shared-pat>?` must not be of the form `shared query <pat>?`: a constructor, unlike a function, cannot be a query.
 
@@ -1481,7 +1545,7 @@ For equality and inequality, the meaning of `v1 <relop> v2` depends on the compi
 === Tuples
 
 Tuple expression `(<exp1>, ..., <expn>)` has tuple type `(T1, ..., Tn)`, provided
-`<exp1>`, ..., `<expN>` have types `T1`, ..., `Tn`.
+`<exp1>`, ..., `<expn>` have types `T1`, ..., `Tn`.
 
 The tuple expression `(<exp1>, ..., <expn>)` evaluates the expressions `exp1` ... `expn` in order, trapping as soon as some expression `<expi>` traps. If no evaluation traps and `exp1`, ..., `<expn>` evaluate to values `v1`,...,`vn` then the tuple expression returns the tuple value `(v1, ... , vn)`.