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 support for bound function arguments #291

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Add support for bound function arguments #291

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d327618
Add support for bound function arguments
rossberg Nov 3, 2021
3aa81a1
Comments
rossberg Nov 3, 2021
c5979f8
Comments
rossberg Nov 5, 2021
bf7f1a5
Comments from Joachim
rossberg Nov 8, 2021
97ea0e7
Update spec/Candid.md
rossberg Nov 9, 2021
ffef920
Update spec/Candid.md
rossberg Nov 22, 2021
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
37 changes: 28 additions & 9 deletions spec/Candid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -464,14 +464,26 @@ A *function reference* is described by its function type. For example, they allo
<reftype> ::= func <functype> | ...
```

##### Example
A function reference may be represented by a simple closure, encapsulating a prefix of arguments that have previously been bound. These hidden arguments do not appear in the function type, but will be forwarded implicitly when the function itself is invoked.


##### Examples

```
type engine = service {
search : (query : text, callback : func (vec result) -> ());
}
```

```
type wallet = service {
topup : (amount : nat) -> ();
forward : (call : func () -> ()) -> ();
}
```
In the latter example, the `call` parameter is assumed to be a closure encapsulating a call to another service (including bound arguments) that the wallet executes on its own caller's behalf by invoking the function.


#### Principal References

A *principal reference* points to an identity, such as a canister or a user. Through this, we can authenticate or authorize other services or users. Because the type constructor takes no arguments, it is classified as a _primitive_ type.
Expand Down Expand Up @@ -561,6 +573,7 @@ The types of these values are assumed to be known from context, so the syntax do
| <text>
| true | false
| null
| principal <text> (principal URI)

<consval> ::=
| opt <val>
Expand All @@ -571,9 +584,8 @@ The types of these values are assumed to be known from context, so the syntax do
<fieldval> ::= <nat> = <annval>

<refval> ::=
| service <text> (canister URI)
| func <text> . <name> (canister URI and message name)
| principal <text> (principal URI)
| service <text> (canister URI)
| func <text> . <name> ( <annval>,* )? (canister URI, message name, and possibly bound arguments)

<arg> ::= ( <annval>,* )

Expand Down Expand Up @@ -1064,7 +1076,7 @@ Most Candid values are self-explanatory, except for references. There are two fo
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`.
* `pub(s,n,v*:t*)`, indicates the public method name `n` of the service referenced by `s`, possibly followed by a list of type-annotated bound argument values.
Copy link
Collaborator

Choose a reason for hiding this comment

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

You don’t want to support binding arguments to references?

Why not make it a recursive definition that allows you to bind arguments to any function reference (whether it’s opaque, public, or itself a closure – after all, these are all values of the same type, so binding to them should be allowed).

Suggested change
* `pub(s,n,v*:t*)`, indicates the public method name `n` of the service referenced by `s`, possibly followed by a list of type-annotated bound argument values.
* `closure(f,v*:t*)`, indicates the function reference `f`, followed by a list of type-annotated bound argument values.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ah, yes, that was an oversight. Refactored as you suggest.


#### Notation

Expand Down Expand Up @@ -1188,11 +1200,15 @@ M : <val> -> <reftype> -> i8*
M(ref(r) : service <actortype>) = i8(0)
M(id(v*) : service <actortype>) = i8(1) M(v* : vec nat8)

M(ref(r) : func <functype>) = i8(0)
M(pub(s,n) : func <functype>) = i8(1) M(s : service {}) M(n : text)
M(ref(r) : func <functype>) = i8(0)
M(pub(s,n) : func <functype>) = i8(1) M(s : service {}) M(n : text)
M(pub(s,n,v*:t*) : func <functype>) = i8(2) M(s : service {}) M(n : text) M*(v* : t*)

M(ref(r) : principal) = i8(0)
M(id(v*) : principal) = i8(1) M(v* : vec nat8)

M* : <val>* -> <datatype>* -> i8*
M*(v^N : <datatype>^N) = leb128(N) M(v : <datatype>)^N
Copy link
Contributor

Choose a reason for hiding this comment

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

this will be a breaking change? or the bound argument is stored in R which was not used before?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

No, R is only used if there are reference types that need it, as before. The type is determined from M.

But I think this is a breaking change in so far that a receiver not understanding the new encoding of closures would choke on it. The only way to avoid this is by indeed introducing a separate closure type as a future type, it seems. Hm, that would be ugly...

Copy link
Collaborator

Choose a reason for hiding this comment

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

A new type seems to be appropriate. Not breaking existing stuff is part of our value proposition, and given the complexity of this maybe it’s good if a service can say that they really only support plain function references, but not closures?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Okay, introduced a new (future) type for closures and made it a supertype of func.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Where is the type of v encoded? I’d expect something like

 M*(v^N : <datatype>^N) = leb128(N) I(<datatype>^N)^N  M(v : <datatype>)^N

to match what we do in B

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ah, good catch, fixed.

```


Expand All @@ -1218,10 +1234,13 @@ R((k,v) : k:<datatype>) = R(v : <datatype>)
R : <val> -> <reftype> -> <ref>*
R(ref(r) : service <actortype>) = r
R(id(b*) : service <actortype>) = .
R(ref(r) : func <functype>) = r
R(pub(s,n) : func <functype>) = .
R(ref(r) : func <functype>) = r
R(pub(s,n,v*:t*) : func <functype>) = R*(v* : t*)
R(ref(r) : principal) = r
R(id(b*) : principal) = .

R* : <val>* -> <datatype>* -> <ref>*
R*(v^N : <datatype>^N) = R(v : <datatype>)^N
```

Note:
Expand Down