Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add service initialization parameters #88

Merged
merged 4 commits into from
Sep 15, 2020
Merged

add service initialization parameters #88

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d1e4252
add service initialization parameters
chenyan-dfinity Aug 25, 2020
0966fef
address comments
chenyan-dfinity Aug 25, 2020
f759e57
Update spec/Candid.md
chenyan-dfinity Aug 25, 2020
98d6458
restrict the change to main actor only
chenyan-dfinity Aug 31, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 15 additions & 10 deletions spec/Candid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Candid Specification

Version: 0.1.0
Version: 0.1.1

Date: May 4, 2020
Date: Aug 25, 2020

## Motivation

Expand Down Expand Up @@ -67,7 +67,7 @@ This is a summary of the grammar proposed:
<def> ::= type <id> = <datatype> | import <text>
<actor> ::= service <id>? : (<actortype> | <id>)

<actortype> ::= { <methtype>;* }
<actortype> ::= { <methtype>;* } | <tuptype> -> { <methtype>;* }
<methtype> ::= <name> : (<functype> | <id>)
<functype> ::= <tuptype> -> <tuptype> <funcann>*
<funcann> ::= oneway | query
Expand Down Expand Up @@ -146,8 +146,11 @@ A *service* is a standalone actor on the platform that can communicate with othe

A service's signature is described by an *actor type*, which defines the list of *methods* that the service provides. Each method is described by its *name* and a *function type* describing its signature. The function type can also be given by referring to a type definition naming a function reference type.

There are two stages of a service: uninitialize and installed. An uninitialized service takes *initialization parameters*
for installing service on the platform. Once it is installed, the parameters are removed from the service signature.

```
<actortype> ::= { <methtype>;* }
<actortype> ::= { <methtype>;* } | <tuptype> -> { <methtype>;* }
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also allow forming

... | <tuptype> -> <id>

where <id> refers to an initialised actor type.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we? It's symmetric with functions, which don't allow <tuptype> -> <id>. What does (nat) -> service (int) -> { f: () -> () } mean? Initializing this service gets another uninitialized service?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I didn't suggest that you can nest them, thus initialised actor type. Only that you can write this:

type A = service {...};
type B = service (Nat) -> A;

The id can only be a non-arrow type, i.e.,

type C = service (Nat) -> B;

would be an error.

<methtype> ::= <name> : (<functype> | <id>)
```
We identify `<methtype>` lists in an actor type up to reordering.
Expand Down Expand Up @@ -432,9 +435,9 @@ type tree = variant {

A third form of value are *references*. They represent first-class handles to (possibly remote) *functions*, *services*, or *principals*.

#### Actor References
#### Service References

An *actor reference* points to a service and is described by an actor type. Through this, services can communicate connections to other services.
A *service reference* points to a service and is described by an actor type. Through this, services can communicate connections to other services.

```
<reftype> ::= ... | service <actortype>
Expand Down Expand Up @@ -547,7 +550,7 @@ For upgrading data structures passed between service and client, it is important

That is, outbound message results can only be replaced with a subtype (more fields) in an upgrade, while inbound message parameters can only be replaced with a supertype (fewer fields). This corresponds to the notions of co-variance and contra-variance in type systems.

Subtyping applies recursively to the types of the fields themselves. Moreover, the directions get *inverted* for inbound function and actor references, in compliance with standard rules.
Subtyping applies recursively to the types of the fields themselves. Moreover, the directions get *inverted* for inbound function and service references, in compliance with standard rules.

### Rules

Expand Down Expand Up @@ -803,6 +806,7 @@ Likewise, there are two forms of Candid values for function references:
* `ref(r)` indicates an opaque reference, understood only by the underlying system.
* `pub(s,n)`, indicates the public method name `n` of the service referenced by `s`.

Note that service references for uninitialized services are not supported at the moment.

#### Notation

Expand Down Expand Up @@ -856,9 +860,9 @@ T(<nat>:<datatype>) = leb128(<nat>) I(<datatype>)
T : <reftype> -> i8*
T(func (<datatype1>*) -> (<datatype2>*) <funcann>*) =
sleb128(-22) T*(<datatype1>*) T*(<datatype2>*) T*(<funcann>*) // 0x6a
T(service {<methtype>*}) =
sleb128(-23) T*(<methtype>*) // 0x69
T(principal)= sleb128(-24) // 0x68
T(service (<datatype>*) -> {<methtype>*}) =
sleb128(-23) T*(<datatype>) T*(<methtype>*) // 0x69
T(principal) = sleb128(-24) // 0x68

T : <methtype> -> i8*
T(<name>:<datatype>) = leb128(|utf8(<name>)|) i8*(utf8(<name>)) I(<datatype>)
Expand Down Expand Up @@ -1004,6 +1008,7 @@ Note:

To enable convenient debugging, we also specify a text format for Candid values.
The types of these values are assumed to be known from context, so the syntax does not attempt to be self-describing.
Note that service references for uninitialized services are not supported at the moment.

```
<val> ::=
Expand Down