Bluish Coder: pony

Reference Capabilities, Consume and Recover in Pony

2017-07-31T18:00:00+12:00

I've written about reference capabilities in the Pony programming language spread across some of my other posts but haven't written about them directly. This post is my attempt to provide an intuitive understanding of reference capabilities and when to use consume and recover. Hopefully this reduces the confusion when faced with reference capability compilation errors and the need to memorize capability tables.

Reference capabilities are used to control aliasing. Controlling aliasing is important when sharing data to avoid data races in the presence of multiple threads. An example of aliasing is:

let a: Object = create_an_object()
let b: Object = a

In that snippet, 'b' is an alias to the object referenced by 'a'. If I pass 'b' to a parallel thread then the same object can be mutated and viewed by two different threads at the same time resulting in data races.

Reference capabilities allow annotating types to say how they can be aliased. Only objects with a particular set of reference capabilities can be shared across actors.

tag - opaque reference

A tag reference capability is an opaque reference to an object. You cannot read or write fields of the object referenced through a tag alias. You can store tag objects, compare object identity and share them with other actors. The sharing is safe since no reading or writing of state is allowed other than object identity.

let a: Object tag = create_a_tag()
let b: Object tag = a
if a is b then ...we're the same object... end

There is also the digestof operator that returns a unique unsigned 64 bit integer value of an object. This is safe to use on tag:

let a: Object tag = create_a_tag()
env.out.print("Id is: " + (digestof a).string())

The tag reference capability is most often used for actors and passing references to actors around. Actor behaviours (asynchronous method calls) can be made via tag references.

val - immutable and sharable

A val reference capability on a variable means that the object is immutable. It cannot be written via that variable. Only read-only fields and methods can be used. Aliases can be shared with other actors because it cannot be changed - there is no issue of data races when accessed from multiple threads. There can be any number of aliases to the object but they all must be val.

let a: Object val = create_an_object()
let b: Object val = a
let c: Object val = a
call_some_function(b)
send_to_an_actor(c)

All the above are valid uses of val. Multiple aliases can exist within the same actor or shared with other actors.

ref - readable, writable but not sharable

The ref reference capability means the object is readable and writable but only within a single actor. There can exist multiple aliases to it within an actor but it cannot be shared with other actors. If it were sharable with other actors then this would allow data races as multiple threads of control read or write to it in a non-deterministic manner.

let a: Object ref = create_a_ref_object()
let b: Object ref = a
call_some_function(b)

The above are valid uses of ref if they are occuring within a single actor. The following are invalid uses - they will result in a compile error:

let a: Object ref = create_a_ref_object()
send_to_an_actor(a)
let b: Object val = a

The send_to_an_actor call would result in an alias of a being accessible from another thread. This would cause data races so is disallowed and results in a compilation error. The assignment to an Object val is also a compilation error. The reasoning for this is access via b would assume that the object is immutable but it could be changed through the underlying alias a. If b were passed to another actor then changes made via a will cause data races.

iso - readable, writable uniquely

The iso reference capability means the object is readable and writable but only within a single actor - much like ref. But unlike ref it cannot be aliased. There can only be one variable holding a reference to an iso object at a time. It is said to be 'unique' because it can only be written or read via that single unique reference.

let a: Object iso = create_an_iso_object()
let b: Object iso = a
call_some_function(a)

The first line above creates an iso object. The other two lines are compilation errors. The assignment to b attempts to alias a. This would enable reading and writing via a and b which breaks the uniqueness rule.

The second line calls a function passing a. This is an implicit alias of a in that the parameter to call_some_function has aliased. It is readable and writable via a and the parameter in call_some_function.

When it comes to fields of objects things get a bit more complicated. Reference capabilities are 'deep'. This means that the capability of an enclosing object affects the capability of the fields as seen by an external user of the object. Here's an example that won't work:

class Foo
  var bar: Object ref = ...

let f: Foo iso = create_a_foo()
let b: Object ref = create_an_object()
f.bar = b

If this were to compile we would have a ref alias alive in b and another alias to the same object alive in the bar field of f. We could then pass our f iso object to another actor and that actor would have a data race when trying to use bar since the original actor also has an alias to it via b.

The uniqueness restriction would seem to make iso not very useful. What makes it useful is the ability to mark aliases as no longer used via the consume keyword.

consume - I don't want this alias

The consume keyword tells Pony that an alias should be destroyed. Not the object itself but the variable holding a reference to it. By removing an alias we can pass iso objects around.

let a: Object iso = create_an_iso_object()
let b: Object iso = consume a
call_some_function(consume b)

This snippet creates an iso object referenced in variable a. The consume in the second line tells Pony that a should no longer alias that object. It's floating around with nothing pointing to it now. Pony refers to this state as being 'ephemeral'. At this point the variable a doesn't exist and it is a compile error to use it further. The object has no aliases and can now be assigned to another variable, in this case b. This meets the requirements of iso because there is still only one reference to the object, via b.

The function call works in the same manner. The consume b makes the object ephemeral and can then be assigned to the parameter for the function and still meet the uniqueness requirements of iso.

iso objects can be sent to other actors. This is safe because there is only a single alias. Once it has been sent to another actor, the alias from the original actor cannot read or be written to because the alias it had was consumed:

let a: Object iso = create_an_iso_object()
send_to_an_actor(consume a)

Converting capabilities

Given an iso reference that is consumed, can that ephemeral object be assigned to other reference capabilities other than iso? The answer to that is yes.

Intuitively this makes sense. If you have no aliases to an object then when you alias that object you can make it whatever capability you want - it is like having created a new object, nothing else references it until you assign it. From that point on what you can do with it is restricted by the reference capability of the variable you assigned it to.

let a: Object iso = create_an_iso()
let b: Object val = consume a

let c: Object iso = create_an_iso()
let d: Object ref = consume c;

The above are examples of valid conversions. You can have an iso, make changes to the object, then consume the alias to assign to some other reference capability. Once you've done that you are restricted by that new alias:

let c: Object iso = create_an_iso()
let d: Object ref = consume c;
send_to_an_actor(d)

That snippet is an error as ref cannot be sent to another actor as explained earlier. This is also invalid:

let c: Object iso = create_an_iso()
let d: Object ref = consume c;
send_to_an_actor(c)

Here we are trying to use c after it is consumed. The c alias no longer exists so it is a compile error.

What if you want to go the other way and convert a val to an iso:

let a: Object val = create_a_val()
let b: Object iso = consume a

This is an error. Consuming the a alias does not allow assigning to another reference capability. Because val allows multiple aliases to exist the Pony compiler doesn't know if a is the only alias to the object. There could be others aliases elsewhere in the program. iso requires uniqueness and the compiler can't guarantee it because of this. The same reasoning is why the following is an error:

let a: Object val = create_a_val()
let b: Object ref = consume a

Intuitively we can reason why this fails. ref allows reading and writing within an actor. val requires immutability and can have multiple aliases. Even though we consume a there may be other aliases around, like the iso example before. Writing to the object via the b alias would break the guarantee of any other aliases to a.

Given this, how do you do this type of conversion? This is what the recover expression is used for.

recover - restricted alias conversion

A recover expression provides a block scope where the variables that can enter the scope are restricted based on their reference capability. The restriction is that only objects that you could send to an actor are allowed to enter the scope of the recover expression. That is iso, val and tag.

Within the recover expression you can create objects and return them from the expression as a different reference capability than what you created them as. This is safe because the compiler knows what entered the block, knows what was created within the block, and can track the aliases such that it knows it's safe to perform a particular conversion.

let a: Object val = recover val
                      let b: Object ref = create_a_ref()
                      ...do something...
                      b
                    end

In this snippet we create a ref object within the recover block. This can be returned as a val because the compiler knows that all aliases to that ref object exist within the recover block. When the block scope exits those aliases don't exist - there are no more aliases to the object and can be returned as the reference type of the recover block.

How does the compiler know that the b object wasn't stored elsewhere within the recover block? There are no global variables in Pony so it can't be stored globally. It could be passed to another object but the only objects accessable inside the block are the restricted ones mentioned before (iso, val and tag). Here's an attempt to store it that fails:

var x: Object ref = create_a_ref()
let a: Object val = recover val
                      let b: Object ref = create_a_ref()
                      x = b
                      b
                    end

This snippet has a ref object created in the enclosing lexical scope of the recover expression. Inside the recover an attempt is made to assign the object b to that variable x. Intuitively this should not work - allowing it would mean that we have a readable and writeable alias to the object held in x, and an immutable alias in a allowing data races. The compiler prevents this by not allowing a ref object from the enclosing scope to enter a recover expression.

Can we go the other way and convert a val to a ref using recover? Unfortunately the answer here is no.

let a: Object ref = recover ref
                      let b: Object val = create_a_ref()
                      ...do something...
                      b
                    end

This results in an error. The reason is a val can be stored in another val variable in the enclosing scope because val objects are safely shareable. This would make it unsafe to return a writeable alias to the val if it is stored as an immutable alias elsewhere. This code snippet shows how it could be aliased in this way:

let x: Object val = create_a_val()
let a: Object val = recover val
                      let b: Object val = create_a_ref()
                      x = b
                      b
                    end

We are able to assign b to a variable in the enclosing scope as the x variable is a val which is one of the valid reference capabilities that can be accessed from within the recover block. If we were able to recover to a ref then we'd have a writeable and an immutable alias alive at the same time so that particular conversion path is an error.

A common use for recover is to create objects with a reference capability different to that defined by the constructor of the object:

class Foo
  new ref create() => ...

let a: Foo val = recover val Foo end
let b: Foo iso = recover iso Foo end

The reference capability of the recover expression can be left out and then it is inferred by the capability of the variable being assigned to:

let a: Foo val = recover Foo end
let b: Foo iso = recover Foo end

Two more reference capabilities to go. They are box and trn.

box - allows use of val or ref

The box reference capability provides the ability to write code that works for val or ref objects. A box alias only allows readonly operations on the object but can be used on either val or ref:

let a: Object ref = create_a_ref()
let b: Object val = create_a_val()
let c: Object box = a
let d: Object box = b

This is particularly useful when writing methods on a class that should work for a receiver type of val and ref.

class Bar
  var count: U32 = 0

  fun val display(out:OutStream) =>
    out.print(count.string())

actor Main
  new create(env:Env) =>
    let b: Bar val = recover Bar end
    b.display(env.out)

This example creates a val object and calls a method display that expects to be called by a val object (the "fun val" syntax). The this from within the display method is of reference capability val. This compiles and works. The following does not:

let b: Bar ref = recover Bar end
b.display(env.out)

Here the object is a ref but display expects it to be val. We can change display to be ref and it would work:

fun ref display(out:OutStream) =>
  out.print(count.string())

But now we can't call it with a val object as in our first example. This is where box comes in. It allows a ref or a val object to be assigned to it and it only allows read only access. This is safe for val as that is immutable and it is safe for ref as an immutable view to the ref:

fun box display(out:OutStream) =>
  out.print(count.string())

Methods are box by default so can be written as:

fun display(out:OutStream) =>
  out.print(count.string())

As an aside, the default of box is the cause for a common "new to Pony" error message where an attempt to mutate a field in an object fails with an "expected box got ref" error:

fun increment() => count = count + 1

This needs to be the following as the implicit box makes the this immutable within the method:

fun ref increment() => count = count + 1

trn - writeable uniquely, consumable to immutable

A trn reference capability is writeable but can be consumed to an immutable reference capability, val. This is useful for cases where you want to create an object, perform mutable operations on it and then make it immutable to send to an actor.

let a: Array[U32] trn = recover Array[U32] end
a.push(1)
a.push(2)
let b: Array[U32] val = consume a
send_to_actor(b)

box and ref methods can be called on trn objects:

class Bar
  var count: U32 = 0

  fun box display(out:OutStream) =>
    out.print(count.string())

  fun ref increment() => count = count + 1

actor Main
  new create(env:Env) =>
    let a: Bar trn = recover Bar end
    a.increment()
    a.display(env.out)

This provides an alternative to the "How do I convert a ref to a val?" question. Instead of starting with a ref inside a recover expression you can use trn and consume to a val later.

You can use iso in place of trn in these examples. Where trn is useful is passing it to box methods to perform readonly operations on it. This is difficult with iso as you have to consume the alias everytime you pass it around, and the methods you pass it to have to return it again if you want to perform further operations on it. With trn you can pass it directly.

actor Main
  let out: OutStream

  fun display(b: Bar box) =>
    b.display(out)

  new create(env:Env) =>
    out = env.out

    let a: Bar trn = recover Bar end
    display(a)
    let b : Bar val = consume a
    send_to_actor(b)

The equivalent with iso is more verbose and requires knowledge of ephemeral types (the hat, ^, symbol):

actor Main
  let out: OutStream

  fun display(b: Bar iso): Bar iso^ =>
    b.display(out)
    consume b

  new create(env:Env) =>
    out = env.out

    let a: Bar iso = recover Bar end
    let b: Bar iso = display(consume a)
    let c: Bar val = consume b
    send_to_actor(c)

Capability Subtyping

I've tried to use a lot of examples to help gain an intuitive understanding of the capability rules. The Pony Tutorial has a Capability Subtyping page that gives the specific rules. Although technical seeming the rules there encode our implicit understanding. This section is a bit more complex and isn't necessary for basic Pony programming if you have a reasonable grasp of it intuitively. It is however useful for working out tricky capability errors and usage.

The way to read those rules are that "<:" means "is a subtype of" or "can be substituted for". So "ref :< box" means that a ref object can be assigned to a box variable:

let a: Object ref = create_a_ref()
let b: Object box = a

The effects are transitive. So if "iso^ <: iso" and "iso <: trn" and "trn <: ref" then "iso^ <: ref":

let a: Object iso = create_an_iso()
let b: Object ref = consume a

Notice we start with iso^ which is an ephemeral reference capability. We get ephemeral types with consume. So consuming the iso gives an iso^ which can be assigned to a ref due to the transitive subtyping path above.

Why couldn't we assign the iso directly without the consume? This is explained previously using inutition but following the rules on the subtyping page we see that "iso! <: tag". The ! is for an aliased reference capability. When we do "something = a" we are aliasing the iso and the type of that a in that expression is iso!. This can only be assigned to a tag according to that rule:

let a: Object iso = create_an_iso()
let b: Object tag = a

Notice there is no "iso! <: iso" which tells us that an alias to an iso cannot be assigned to an iso which basically states the rule that iso can't be aliased.

In a previous section I used an ephemeral type in a method return type:

fun display(b: Bar iso): Bar iso^ =>
    b.display(out)
    consume b

This was needed because the result of display was assigned to an iso:

let b: Bar iso = display(consume a)

If we used Bar iso as the return type then the compiler expects us to be aliasing the object being returned. This alias is of type iso!. The error message states that iso! is not a subtype of iso which is correct as there is no "iso! :< iso" rule. Thankfully the error message tells us that "this would be possible if the subcap were more ephemeral" which is the clue that we need the return type to be ephemeral.

Viewpoint Adaption

I briefly mentioned in a previous section that reference capabilities are 'deep' and this is important when accessing fields of objects. It is also important when writing generic classes and methods and using collections.

Viewpoint adaption is described in the combining capabilities part of the tutorial. I also have a post, Borrowing in Pony which works through some examples.

The thing to remember is that a containing objects reference capability affects the reference capabilities of fields and methods when accessed via a user of the container.

let a: Array[Bar ref] iso = recover Array[Bar ref] end
a.push(Bar)
try
  let b: Bar ref = a(0)?
end

Here is an iso array of Bar ref objects. The third line to retrieve an element of the array fails to compile, stating that tag is not a subtype of ref. Where does the tag come from? Intuitively we can reason that we shouldn't be able to get a ref alias of an item in an iso array as that would give us two ref aliases of an item in an iso that could be shared across actors. This can give data races.

Viewpoint adaption encodes this in the type rules. We have receiver, a of type iso, attempting to call the apply method of the array. This method is declared as:

fun apply(i: USize): this->A ?

The this->A syntax is the viewpoint adaption. It states that the result of the call is the reference capability of A as seen by this. In our case, this is an iso and A is a ref. The viewpoint adaption for iso->ref is tag and that's where the tag in the error message comes from.

We could get an immutable alias to an item in the array if the array was trn:

let a: Array[Bar ref] trn = recover Array[Bar ref] end
a.push(Bar)
try
  let b: Bar box = a(0)?
end

The viewpoint adaption table shows that trn->ref gives box. To get a ref item we'd need the array to be ref:

let a: Array[Bar ref] ref = recover Array[Bar ref] end
a.push(Bar)
try
  let b: Bar ref = a(0)?
end

For more on viewpoint adaption I recommend my Borrowing in Pony and Bang, Hat and Arrow posts.

Miscellaneous things

In my examples I've used explicit reference capabilities in types to make it a bit clearer of what is happening. They can be left off in places to get reasonable defaults.

When declaring types the default capability is the capability defined in the class:

class ref Foo

let a: Foo = ...

class val Bar
let b: Bar = ...

The type of a is Foo ref and the type of Bar is Bar val due to the annotation in the class definition. By default classes are ref if they aren't annotated.

The type of an object returned from a constructor is based on the type defined in the constructor:

class Foo
  new ref create() => ...
  new val create_as_val() => ...
  new iso create_as_iso() => ...

let a: Foo val = Foo.create_as_val()

Here the Foo class is the default type ref, but there are constructors that explicitly return ref, val and iso objects. As shown previously you can use recover to change the capability returned by a constructor in some instances.

let a: Foo val = recover Foo.create() end // Ok - ref to val
let b: Foo ref = recover Foo.create_as_val() end // Not Ok - val to ref

As can be seen, converting val to ref using recover is problematic as shown in previous examples.

Conclusion

Reference capabilities are complex for people new to Pony. An intuitive grasp can be gained without needing to memorize tables of conversions. This intuitive understanding requires thinking about how objects are being used and whether such use might cause data races or prevent sharing across actors. Based on that understanding you pick the capabilities to match what you want to use. For those times that errors don't match your understanding use the viewpoint adaption and capability subtyping tables to work out where things are going wrong. Over time your intuitive understanding improves for these additional edge cases.

Borrowing in Pony

2016-07-18T23:00:00+12:00

The 'TL;DR' of this post on how to borrow internal fields of iso objects in Pony is:

To borrow fields internal to an iso object, recover the object to a ref (or other valid capability) perform the operations using the field, then consume the object back to an iso.

Read on to find out why.

In this post I use the term borrowing to describe the process of taking a pointer or reference internal to some object, using it, then returning it. An example from C would be something like:

void* new_foo();
void* get_bar(foo* f);
void  delete_foo(foo* f);

...
void* f = new_foo();
void* b = get_bar(f);
...
delete_foo(f);

Here a new foo is created and a pointer to a bar object returned from it. This pointer is to data internal to foo. It's important not to use it after foo is deleted as it will be a dangling pointer. While holding the bar pointer you have an alias to something internal to foo. This makes it difficult to share foo with other threads or reason about data races. The foo object could change the bar data without the holder of the borrowed pointer to bar knowing making it a dangling pointer, or invalid data, at any time. I go through a real world case of this in my article on using C in the ATS programming language.

Pony has the concept of a reference to an object where only one pointer to that object exists. It can't be aliased and nothing else can read or write to that object but the current reference to it. This is the iso reference capability. Capabilities are 'deep' in pony, rather than 'shallow'. This means that the reference capability of an alias to an object affects the reference capabilities of fields of that object as seen by that alias. The description of this is in the viewpoint adaption section of the Pony tutorial.

The following is a Pony equivalent of the previous C example:

class Foo
  let bar: Bar ref
...
let f: Foo ref = Foo.create()
let b: Bar ref = f.bar

The reference capability of f determines the reference capability of bar as seen by f. In this case f is a ref (the default of class objects) which according to the viewpoint adaption table means that bar as seen by f is also a ref. Intuitively this makes sense - a ref signifies multiple read/write aliases can exist therefore getting a read/write alias to something internal to the object is no issue. A ref is not sendable so cannot be accessed from multiple threads.

If f is an iso then things change:

class Foo
  let bar: Bar ref
...
let f: Foo iso = recover iso Foo.create() end
let b: Bar tag = f.bar

Now bar as seen by f is a tag. A tag can be aliased but cannot be used to read/write to it. Only object identity and calling behaviours is allowed. Again this is intuitive. If we have a non-aliasable reference to an object (f being iso here) then we can't alias internally to the object either. Doing so would mean that the object could be changed on one thread and the internals modified on another giving a data race.

The viewpoint adaption table shows that given an iso f it's very difficult to get a bar that you can write to. The following read only access to bar is ok:

class Foo
  let bar: Bar val
...
let f: Foo iso = recover iso Foo.create() end
let b: Bar val = f.bar

Here bar is a val. This allows multiple aliases, sendable across threads, but only read access is provided. Nothing can write to it. According to viewpoint adaption, bar as seen by f is a val. It makes sense that given a non-aliasable reference to an object, anything within that object that is immutable is safe to borrow since it cannot be changed. What if bar is itself an iso?

class Foo
  let bar: Bar iso = recover iso Bar end
...
let f: Foo iso = recover iso Foo.create() end
let b: Bar iso = f.bar

This won't compile. Viewpoint adaption shows that bar as seen by f is an iso. The assignment to b doesn't typecheck because it's aliasing an iso and iso reference capabilities don't allow aliasing. The usual solution when a field isn't involved is to consume the original but it won't work here. The contents of an objects field can't be consumed because it would then be left in an undefined state. A Foo object that doesn't have a valid bar is not really a Foo. To get access to bar externally from Foo the destructive read syntax is required:

class Foo
  var bar: Bar iso = recover iso Bar end
...
let f: Foo iso = recover iso Foo.create() end
let b: Bar iso = f.bar = recover iso Bar end

This results in f.bar being set to a new instance of Bar so it's never in an undefined state. The old value of f.bar is then assigned to b. This is safe as there are no aliases to it anymore due to the first part of the assignment being done first.

What if the internal field is a ref and we really want to access it as a ref? This is possible using recover. As described in the tutorial, one of the uses for recover is:

"Extract" a mutable field from an iso and return it as an iso.

This looks like:

class Foo
  let bar: Bar ref
... 
let f: Foo iso = recover iso Foo end
let f' = recover iso
           let f'': Foo ref = consume f
           let b: Bar ref = f''.bar
           consume f''
         end

Inside the recover block f is consumed and returned as a ref. The f alias to the object no longer exists at this point and we have the same object but as a ref capability in f''. bar as seen by f'' is a ref according to viewpoint adaption and can now be used within the recover block as a ref. When the recover block ends the f'' alias is consumed and returned out of the block as an iso again in f'.

This works because inside the recover block only sendable values from the enclosing scope can be accessed (ie. val, iso, or tag). When exiting the block all aliases except for the object being returned are destroyed. There can be many aliases to bar within the block but none of them can leak out. Multiple aliases to f' can be created also and they are not going to leaked either. At the end of the block only one can be returned and by consuming it the compiler knows that there are no more aliases to it so it is safe to make it an iso.

To show how the ref aliases created within the recover block can't escape, here's an example of an erroneous attempt to assign the f' alias to an object in the outer scope:

class Baz
  var a: (Foo ref | None) = None
  var b: (Foo ref | None) = None

  fun ref set(x: Foo ref) =>
    a = x
    b = x

class Bar

class Foo
  let bar: Bar ref = Bar

var baz: Baz iso = recover iso Baz end
var f: Foo iso = recover iso Foo end
f = recover iso
      let f': Foo ref = consume f
      baz.set(f')
      let b: Bar ref = f'.bar
      consume f'
    end

If this were to compile then baz would contain two references to the f' object which is then consumed as an iso. f would contain what it thinks is non-aliasable reference but baz would actually hold two additional references to it. This fails to compile at this line:

main.pony:20:18: receiver type is not a subtype of target type
          baz.set(f')
                 ^
Info:
main.pony:20:11: receiver type: Baz iso!
              baz.set(f')
              ^
main.pony:5:3: target type: Baz ref
      fun ref set(x: Foo ref) =>
      ^
main.pony:20:18: this would be possible if the arguments and return value were all sendable
              baz.set(f')
                     ^

baz is an iso so is allowed to be accessed from within the recover block. But the set method on it expects a ref receiver. This doesn't work because the receiver of a method of an object is also an implicit argument to that method and therefore needs to be aliased. In this way it's not possible to store data created within the recover block in something passed into the recover block externally. No aliases can be leaked and the compiler can track things easily.

There is something called automatic receiver recovery that is alluded to in the error message ("this would be possible...") which states that if the arguments were sendable then it is possible for the compiler to work out that it's ok to call a ref method on an iso object. Our ref arguments are not sendable which is why this doesn't kick in.

A real world example of where all this comes up is using the Pony net/http package. A user on IRC posted the following code snippet:

use "net/http"
class MyRequestHandler is RequestHandler

  let env: Env

  new val create(env': Env) =>
    env = env'

  fun val apply(request: Payload iso): Any =>
    for (k, v) in request.headers().pairs() do
      env.out.print(k)
      env.out.print(v)
    end

    let r = Payload.response(200)
    r.add_chunk("Woot")
    (consume request).respond(consume r)

The code attempts to iterate over the HTTP request headers and print them out. It fails in the request.headers().pairs() call, complaining that tag is not a subtype of box in the result of headers() when calling pairs(). Looking at the Payload class definition shows:

class iso Payload
  let _headers: Map[String, String] = _headers.create()

  fun headers(): this->Map[String, String] =>
    _headers

In the example code request is an iso and the headers function is a box (the default for fun). The return value of headers uses an arrow type. It reads as "return a Map[String, String] with the reference capability of _headers as seen by this". In this example this is the request object which is iso. _headers is a ref according to the class definition. So it's returning a ref as seen by an iso which according to viewpoint adaption is a tag.

This makes sense as we're getting a reference to the internal field of an iso object. As explained previously this must be a tag to prevent data races. This means that pairs() can't be called on the result as tag doesn't allow function calls. pairs() is a box method which is why the error message refers to tag not being a subtype of box.

To borrow the headers correctly we can use the approach done earlier of using a recover block:

fun val apply(request: Payload iso): Any =>
  let request'' = recover iso
    let request': Payload ref = consume request
    for (k, v) in request'.headers().pairs() do
      env.out.print(k)
      env.out.print(v)
    end
    consume request'
  end
  let r = Payload.response(200)
  r.add_chunk("Woot")
  (consume request'').respond(consume r)

In short, to borrow fields internal to an iso object, recover the object to a ref (or other valid capability) perform the operations using the field, then consume the object back to an iso.

Exploring actors in Pony

2016-05-11T18:00:00+12:00

Pony is an actor oriented programming language. In Pony Actors are objects that can send and receive messages asychronously while processing their received messages sequentially and in parallel with other actors processing their messages. They are the unit of concurrency in the language. Each actor is similar to a lightweight thread of execution in languages that support those.

For background on the Actor model of computation there are a lot of papers at the erights.org actor page. They make good background reading. In this post I'm going to go through some things I've learnt while learning Pony and using actors in some small projects.

An actor is defined very similar to a class. The following class definition creates a counter that can be incremented and decremented:

class Counter
  var count: U32

  new create(start: U32) =>
    count = 0

  fun ref inc() =>
    count = count + 1

  fun ref dec() =>
    count = count - 1

  fun get(): U32 =>
    count

actor Main
  new create(env: Env) =>
    let c1 = Counter(0)
    c1.inc()
    c1.inc()
    env.out.print(c1.get().string())

The first thing to note here is the actor called Main. Every Pony program has an actor called Main that is the entry point for the program. This actor is instantiated by the Pony runtime and the constructor is expected to perform the program operations in a similar manner to how the main functions works in the C programming language.

The Counter class is created in the constructor of Main and incremented a couple of times. All this happens in a single thread of control. Because it operates within a single thread there is no concurrent access to the state held by the counter. This makes it safe to call the inc, dec and get methods. The order of operations is well defined. We can only pass the counter instance to another thread if we give up any aliases to it so we can ensure that it can be safely used elsewhere or if we make it immutable so that nothing can change it at any time.

Behaviours

If we want to use a Counter from multiple threads but still allow modification then making it an actor is an option. This can be done by changing the class keyword to actor and the methods to behaviours:

actor Counter
  var count: U32

  new create(start: U32) =>
    count = 0

  be inc() =>
    count = count + 1

  be dec() =>
    count = count - 1

  be display(out:OutStream) =>
    out.print(count.string())

actor Main
  new create(env: Env) =>
    let c1 = Counter(0)
    c1.inc()
    c1.inc()
    c1.display(env.out)

A behaviour is introduced with the be keyword. It is like a function except that it is asynchronous. When a behaviour is called it is not executed immediately.

Internally each actor has a queue for holding messages. Each behaviour call on an actor puts a message in that queue to run that behaviour at some future point in time. The actor runs a message loop that pops a message off the queue and runs the associated behaviour. When the behaviour completes executing then it will run the next one in the queue for that actor. If there are none left to run the the actor is idle until a behaviour is called. During this idle period it can perform garbage collection. The Pony runtime has a scheduler that uses operating system threads to execute actor behaviours. In this way multiple behaviours for different actors can be running on many OS threads at the same time.

The behaviours that are queued for an individual actor are executed sequentially. Two behaviours for the same actor will never run concurrently. This means that within a behaviour the actor has exclusive access to its internal state. There is no need for locks or guards to control access. For this reason it helps to think of actors as a unit of sequentiality rather than of a parallelism. See the actors section of the tutorial for more on this.

The main change with the conversion of the counter class is there is no longer a get method. It's replaced by a display behaviour that outputs the string. get was removed because behaviours are executed asynchronously so they cannot return the result of the function - they've returned to the caller before the body of the behaviour is executed. They always return the object the behaviour was called on. This makes chaining behaviour calls possible:

    let c1 = Counter(0)
    c1.inc()
      .inc()
      .display(env.out)

tag reference capability

A class defaults to a reference capability of ref. An actor defaults to tag. A tag only allows object identification. No read or write operations are allowed but you can alias tag objects and you can pass them to other actors. This is safe since the holder of a tag alias can't view or modify the state. It can call behaviours on it though. This is safe because behaviours are queued for sequential processing at a future point in time - access to the state of the actor is serialized through behaviours.

Simulating return values

How do you deal with returning values from behaviours if they don't support return values? One approach is to pass an object to the behaviour that it uses as a callback with the result. For the counter example this could look like:

actor Counter
  ...as before...

  be get(cb: {(U32)} iso) =>
    cb(count)

actor Main
  new create(env: Env) =>
    let c1 = Counter(0)
    c1.inc()
      .inc()
      .get(recover lambda (x:U32)(env) => env.out.print(x.string()) end end)

Here the get behaviour receives a closure as an argument. This is called passing a closure that prints the value out. When get is executed asynchronously it's safe for it to pass the count value to the closure. The closure can't modify it. The closure itself is an iso reference capability so nothing else but the behaviour is accessing it.

This approach leads to a very 'callback' style of programming. It can feel like programming in continuation passing style at times. It requires careful design when dealing with error handling. Pony includes a promises library to help manage this.

Promises

The promises library provides the ability to pass callbacks, handle errors and chain promises together to make it easier to manage callback style programming. The counter example converted to use promises looks like:

use "promises"

actor Counter
  ...as before...

  be get(p: Promise[U32]) =>
    p(count) 

actor Main
  new create(env: Env) =>
    let c1 = Counter(0)
    let p = Promise[U32]
    c1.inc()
      .inc()
      .get(p)
    p.next[None](recover lambda ref(x:U32)(env) => env.out.print(x.string()) end end)

The get method has been changed to take a Promise[U32]. The Promise type is a generic type and here it is indexed over the U32 value that it will be provided with. In the Main actor a promise is created and passed to get. Then the next method is called on the promise to tell it what to do when a value is provided to it. In this case it's the same closure as in the previous example so there's not much of a win here.

What promises do provide though is a way to handle failure. A callback used in the promise can raise an error and the promise will try the next operation in the chain. Chained promises can manipulate values as they're passed down the chain to form a pipeline of operations.

The boilerplate to create the promise and pass it to the behaviour can be hidden by a method on the actor:

actor Counter
  ...as before...

  be myget(p: Promise[U32]) =>
    p(count)

  fun tag get(): Promise[U32] =>
    let p = Promise[U32]
    myget(p)
    p

actor Main
  new create(env: Env) =>
    let c1 = Counter(0)
    c1.inc()
      .inc()
      .get().next[None](recover lambda ref(x:U32)(env) => env.out.print(x.string()) end end)

In this example the get method creates the promise and passes it to the behaviour then returns the promise. The caller can then use method chaining to call next on the promise to perform the action.

Notice that the get method has a tag reference capability. This is required to allow other actors to call it. A reference to an actor has the tag capability so only behaviours and tag methods can be called with it. A tag method can't modify internal state - all it can do is call behaviours on the actor - so this is safe to be called externally. It would be a compile error if the method attempted to view or modify actor state.

The following demonstrates promise chaining:

actor Counter
  ...as before...

  fun tag get_string(): Promise[String] =>
    get().next[String](object iso
                         fun ref apply(x:U32): String => x.string()
                       end)

actor Main
  new create(env: Env) =>
    let c1 = Counter(0)
    c1.inc()
      .inc()
      .get_string().next[Main](recover this~print(env.out) end)

  be print(out:OutStream, s: String) =>
    out.print(s)

In this case we want a String from the behaviour call. The get_string method on Counter calls get and chains the next callback to be one that returns a result of type `String. It just does a conversion by calling the string method. I use an object literal here instead of a closure for clarity.

The caller in Main calls get_string and chains the returned promise with another callback. This callback uses partial application to call the print behaviour on Main to print the string. The next call uses Main to parameterize the promise result as calling the print behaviour returns the receiver - in this case Main.

The result of this is that when the get behaviour is executed it calls the first promise in the chain to return the result. That converts the U32 to a String. The next promise in the chain is then called which calls print on the Main actor. That behaviour gets queued and eventually run to output the result.

Which is best to use, promises or callbacks? It depends on what the objects are doing. For single return values with an error case then promises are a good approach. For objects that need to callback multiple times then a callback or notifier object may be a better choice. For an example of the latter, see the net packages use of various notifier classes like TCPConnectionNotify to provide notification of different states in the TCP connection lifetime:

interface TCPConnectionNotify
  fun ref accepted(conn: TCPConnection ref)
  fun ref connecting(conn: TCPConnection ref, count: U32)
  fun ref connected(conn: TCPConnection ref)
  fun ref connect_failed(conn: TCPConnection ref)
  fun ref auth_failed(conn: TCPConnection ref)
  fun ref sent(conn: TCPConnection ref, data: ByteSeq): ByteSeq ?
  fun ref sentv(conn: TCPConnection ref, data: ByteSeqIter): ByteSeqIter ?
  fun ref received(conn: TCPConnection ref, data: Array[U8] iso)
  fun ref expect(conn: TCPConnection ref, qty: USize): USize
  fun ref closed(conn: TCPConnection ref)

Sendable objects

As behaviours are sent asycnhronously this means the arguments to those behaviours must be sharable. The passing and sharing section of the tutorial makes the distinction between 'passing' and 'sharing' objects.

In 'passing' an object from one actor to another the originating actor is giving up ownership. It can no longer access the object after giving it to the receiving actor. This is the iso reference capability. The sending actor must consume it when passing it to the receiver:

actor Main
  new create(env: Env) =>
    let a = recover iso String end
    let b = Something
    b.doit(consume a)

actor Something
  be doit(s: String iso) =>
    s.append("Hello World")

In 'sharing' an object you want both the originating actor and the receiver (and any others) to be able to read from the object. Nothing should be able to write to it. This is the val reference capability:

class Data
  var count: U32 = 0

  fun ref inc() =>
    count = count + 1

actor Main
  new create(env: Env) =>
    let a: Data trn = recover trn Data end
    a.inc()

    let d: Data val = consume a
    let s1 = Something(env.out)
    let s2 = Something(env.out)
    s1.doit(d)
    s2.doit(d)

actor Something
  let _out: OutStream

  new create(out: OutStream) =>
    _out = out

  be doit(d: Data val) =>
    _out.print("Got " + d.count.string())

This example has a Data class with an integer count field. In the Main actor we create an instance as a trn reference capability. This is used for objects that you want to write to initially but give out immutable access to later. While we hold the mutable trn reference we increment it and then consume it to get an immutable val reference capability for it. The old a alias is no longer usable at this point - no writeable aliases to the object exist. Because it is immutable we can now pass it to as many actors as we want and they get read only access to the objects fields and methods.

Another sharable type is the tag reference capability. This provides only identity access to an object. A receiver of a tag object can't read or write fields but it can call behaviours. It is the reference capability used for actors and is what you use to pass actors around. The previous sharing example uses this to pass the env.out object around. The OutStream is an actor.

It's important to keep in mind that creating aliases of objects doesn't copy the object. It's a new variable pointing to the same object. There is no copy operation involved in passing the Data val objects around. Although the capability is called 'val' it is not a 'value object'. The two Something actors have the same Data object in terms of object identity. The val only means 'immutable'.

The reference capabilities and the checking by the type system is what allows avoiding copies to be safe in the presence of multiple actors. This does mean that if you have a ref object you can't pass it to an actor. This is a compile error:

actor Something
  be doit(s: String ref) =>
  None

Only val, iso and tag can be used as an argument to a behaviour. This will also fail to compile:

actor Main
  new create(env: Env) =>
    let a = recover ref String end
    a.append("Hello World")
    let b = Something
    b.doit(a)

actor Something
  be doit(s: String val) =>
    None

Here we have a String ref and are trying to pass it to a behaviour expecting a String val. It is not possible to convert a ref to a val. A ref provides read and write access to the object. Multiple aliases to the same ref object can exist within a single actor. This is safe because behaviour execution within an actor is sequential. All of these aliases would need to be consumed to safely get a val alias. The type system doesn't (and probably couldn't) prove that all aliases are consumed at the time of converting to a val so it is not possible to do the conversion.

This is a case where a copy is needed:

actor Main
  new create(env: Env) =>
    let a = recover ref String end
    a.append("Hello World")
    let b = Something
    b.doit(a.clone())

The clone method on String returns a String iso^ which is convertable automatically to a String val by virtue of the fact that it has no aliases (The ^ part of the type). See capability subtyping for details

Cloning creates a copy distinct from the original. They have different identities and is a less efficient operation so it's worthwhile examining the data being passed around and seeing if it's possible to avoid holding multiple references to data and use the strictest reference capability to avoid aliasing.

Blocking operations

Pony has no blocking operations (outside of using the C FFI). In languages like Erlang it's common to do a blocking receive within a function to wait for a message and operate on it. In Pony this is implicitly done by actors in their event loop, hidden from the programmer. A behaviour call queues the message and it is executed when it's popped off the queue. You can't block for a message within the body of a behaviour itself.

This results in having to change the programming mode from "wait for data and do something" to "notify me of data when it's available". Instead of blocking for N seconds within a behaviour you create a timer to notify the actor of something 'N' seconds later.

The Pony standard library is structured in this way to use notifier objects, callbacks and promises to make programming in this style easier.

Causal Messaging

Data races can be difficult to avoid in the presence of asynchronous executation of threads. Pony has a message ordering guarantee to make the following type of code safe:

actor Counter
  let _out: OutStream
  var count: U32 = 0

  new create(out: OutStream) =>
    _out = out

  be inc() =>
    count = count + 1

  be dec() =>
    count = count - 1
    if count == 0 then _out.print("counter is destoyed") end

actor Something
  be doit(counter: Counter) =>
    counter.dec()

actor Main
  new create(env: Env) =>
    let c1 = Counter(env.out)
    let c2 = Something
    c1.inc()
    c2.doit(c1)

In this example the Counter object does something when the count is decremented to zero. In the Main actor a counter is created, incremented and passed to another actor where it is decremented. The inc and doit calls are on different actors and therefore are executed asynchronously. It's important that the inc call executes before the dec call in the doit behaviour of the other actor.

Pony has a message ordering guarantee, called 'causal messaging', to ensure this ordering happens. This is described in a forum thread discussion as:

[...] Pony makes a messaging order guarantee that's much stronger than is typical for the actor model. It guarantees causal messaging. That is, any message that is a "cause" of another message (i.e. was sent or received by an actor prior to the message in question) is guaranteed to arrive before the "effect" if they have the same destination.

For more information the paper Fully Concurrent Garbage Collection of Actors on Many-Core Machines goes into detail about how it works.

Garbage Collection

Actor's have their own garbage collection heap. Garbage collection occurs between behaviour calls on the actor. This allows GC to occur for an actor without interrupting execution of other actors. The runtime detects when it is no longer possible for an actor to receive messages and will garbage collect the actor itself. This can avoid the need to implement a 'poison pill' protocol whereby the actor receives a message to say it can terminate.

Even with this automatic actor garbage detection in place there are times when it is necessary to implement a shutdown protocol. An actor may be receiving notification callbacks - the actor sending the callbacks needs to be told to stop sending the messages so the system can detect that the receiver can be garbage collected. In my IMAP Idle monitor I use dispose methods to cancel timers or close TCP connections. A Pony library class called a Custodian holds a collection of actors to be disposed and calls dispose on each one when its own dispose behaviour is called. This results in the runtime detecting that none of the actors in the application can receive messages anymore and the entire application terminates.

One thing to be careful of with garbage collection only happening between behaviour calls is that a long running behaviour will not GC during its execution. Simple benchmark applications that do everything in the Main actors constructor exhibit this. They use large amounts of memory due to no GC happening if the benchmark doesn't call a behaviour on the actor.

Bang, Hat and Arrow in Pony

2016-05-04T18:00:00+12:00

If you've looked at Pony programming language code you've probably seen use of punctuation symbols in places and wondered what they meant. This post is an attempt to explain three of those - the bang, hat and arrow (!, ^ and -> respectively). Note that this is my understanding based on usage, reading the tutorials and watching videos so there may be errors. I welcome corrections!

Bang

The bang symbol (otherwise known as an exclamation mark) combined with a type name can be thought of as the type of an alias of the given type. Having an alias of an object means having another reference to that object. So an alias to a String iso is of type String iso!. This matters mostly in generic code which will be explained later but it does come up in error messages.

If you see ! in an error message like "iso! is not a subtype of iso" this means you are probably trying to assign an object that cannot be aliased without first consuming it.

If you see ! in a type declaration in code like "let foo: A!" then you can read this as "replace A! with a type that can safely hold an alias to A". If A is a String iso then A! would be a String tag for example (following the rules for aliased substitution.

Bang in errors

The following code demonstrates something that is often encountered by first time Pony users:

class Something

actor Main
  new create(env: Env) =>
    let a = recover iso Something end
    Foo(a)

actor Foo
  new create(s: Something iso) =>
    None

Here we have a class called Something. A new instance of it is created in the Main actor with reference capability iso. A new Foo actor is created passing this instance to it. This will fail to compile as we are aliasing the Something object held in a. a holds a reference to it and the variable s holding the argument to the Foo constructor is holding a reference to it at the same time. Objects with a reference capability of iso cannot have more than one reference to it. The error from the compiler will look like:

Error:
e1/main.pony:6:9: argument not a subtype of parameter
    Foo(a)
        ^
    Info:
    e1/main.pony:9:14: parameter type: Something iso
      new create(s: Something iso) =>
                 ^
    e1/main.pony:6:9: argument type: Something iso!
        Foo(a)
            ^
    e1/main.pony:1:1: Something iso! is not a subtype of Something iso: iso! is not a subtype of iso

This error states that the expected type of the parameter for the Foo constructor is of type Something iso but the type that we passed is a Something iso!. It further explains things by noting that Something iso! is not a subtype of Something iso because iso! is not a subtype of iso.

Armed with the knowledge that the bang symbol means the type for an alias this can be read as the argument passed was an alias to a Something iso. This is an error as iso cannot be aliased - this is what iso! is not a subtype of iso means. The subtyping relationship for aliases is outlined in the Capability Subtyping section of the tutorial.

The code can be fixed by consuming the a so it is no longer aliased:

let a = recover iso Something end
Foo(consume a)

Bang in generics

The other place where you'll see the alias type is in generic code. The following non-generic code compiles fine:

class Something
  let a: U8

  new create(x: U8) =>
    a = x

actor Main
  new create(env: Env) =>
    let aint = Something(42)

U8 defaults to val reference capability which can be aliased. This allows the assignment to the field a in Something which is aliasing the x object. If we make this a generic so that any type can be used then it fails to compile:

class Something[A]
  let a: A

  new create(x: A) =>
    a = x

actor Main
  new create(env: Env) =>
    let aint = Something[U8](42)

The error is:

Error:
e3/main.pony:5:7: right side must be a subtype of left side
    a = x
      ^
    Info:
    e3/main.pony:4:17: right side type: A #any !
      new create(x: A) =>
                    ^
    e3/main.pony:5:5: left side type: A #any
        a = x
        ^
    e3/main.pony:4:17: A #any ! is not a subtype of A #any: the subtype has no constraint
      new create(x: A) =>
                ^

For now, ignore the #any in the error message. I'll expand on this later but it's informing us that the type A is unconstrained and can have any reference capability.

The error states that x is an A! but a is an A and A! is not a subtype of A so the assignment cannot happen.

This occurs Because A is unconstrained. It can be any reference capability. Therefore the code must be able to be compiled under the assumption that the most restrictive reference capability can be used. It works fine with val, which can be aliased, but not with iso which cannot. Therefore the generic code cannot be compiled. You can see how iso would fail by expanding a version using String iso:

class Something
  let a: String  iso

  new create(x: String iso) =>
    a = x

actor Main
  new create(env: Env) =>
    let aint = Something(recover iso String end)

The error is:

Error:
e5/main.pony:5:7: right side must be a subtype of left side
    a = x
      ^
    Info:
    e5/main.pony:4:17: right side type: String iso!
      new create(x: String iso) =>
                    ^
    e5/main.pony:2:10: left side type: String iso
      let a: String  iso
             ^
    e5/main.pony:4:17: String iso! is not a subtype of String iso: iso! is not a subtype of iso
      new create(x: String iso) =>
                    ^

This is the same error that the generic code is giving us. The generic code can be fixed in a few ways. The first is to constrain the type so that it is a specific reference capability that works. Here it is changed to val:

class Something[A: Any val]
  let a: A

  new create(x: A) =>
    a = x

actor Main
  new create(env: Env) =>
    let aint = Something[U8](42)

The A: Any val syntax constrains the type parameter to be a subtype of the type after the :. In this case, any type with a reference capability of val. This won't work if you want to be able to use any aliasable type (eg ref as well as val):

class Something[A: Any val]
  let a: A

  new create(x: A) =>
    a = x

actor Main
  new create(env: Env) =>
    let aint = Something[U8](42)
    let bint = Something[String ref](recover ref String end)

The error here is obvious in that we are trying to pass a ref parameter to a function expecting a val. Pony generics solves this by allowing code to be polymorphic over the reference capability. There are specific annotations for classes of reference capabilities. They are:

#read  = { ref, val, box }                = Anything you can read from
#send  = { iso, val, tag }                = Anything you can send to an actor
#share = { val, tag }                     = Anything you can send to more than one actor
#any   = { iso, trn, ref, val, box, tag } = Default of a constraint
#alias = {ref,val, box, tag}              = Set of capabilities that alias as themselves (used by compiler)

A version that will work for ref, val and box becomes:

class Something[A: Any #read]
  let a: A

  new create(x: A) =>
    a = x

actor Main
  new create(env: Env) =>
    let aint = Something[U8](42)
    let bint = Something[String ref](recover ref String end)

But what if you want it to work with non-aliasable types like iso? A solution is to consume the parameter:

class Something[A]
  let a: A

  new create(x: A) =>
    a = consume x

actor Main
  new create(env: Env) =>
    let aint = Something[U8](42)
    let bint = Something[String ref](recover ref String end)
    let cint = Something[String iso](recover iso String end)

Another solution is to declare the field type to be A! instead of A. In the String iso case using A means String iso which cannot hold an alias. Using A! means String iso! which should be read as "a type that can safely alias a String iso". Looking at the Aliased substitution table this is a tag:

class Something[A]
  let a: A!

  new create(x: A) =>
    a = x

actor Main
  new create(env: Env) =>
    let aint = Something[U8](42)
    let bint = Something[String ref](recover ref String end)
    let cint = Something[String iso](recover iso String end)

In this case we are using ! to tell the compiler to use a reference capability that works for whatever the type of A is. An iso becomes a tag, a trn becomes a box, a ref stays a ref, etc.

Hat

The hat symbol (or ^) is an ephemeral type. It's the type of an object that is not assigned to a variable. consume x is used to prevent aliasing of x but at the point of being consumed and before it is assigned to anything else, what type is it? If x is type A then the type of consume x is A^. Constructors always return an ephemeral type as they create objects and return them but they aren't yet assigned to anything.

The following example creates a Box type that acts like single instance array of String iso objects. A value can be stored and updated. A utility function Foo.doit takes a String iso as an argument. It's stubbed out since it doesn't need to do anything for the example. The main code creates a Box, updates it, and calls the utility function on it.

class Box
  var a: String iso

  new create(x: String iso) =>
    a = consume x

  fun ref update(x: String iso): String iso =>
    let b = a = consume x
    consume b

primitive Foo
  fun doit(s: String iso) =>
    None

actor Main
  new create(env: Env) =>
    let a = Box(recover iso String end)
    let b = a.update(recover iso String end)
    Foo.doit(consume b)

Some things to note based on prior discussion. The create method consumes the argument to prevent aliasing. The update function also consumes the argument to prevent aliasing. It uses the destructive read syntax to assign the argument x to the field a and assign the old value of a to b to avoid aliasing. Unfortunately this example fails to compile:

Error:
f3/main.pony:19:14: argument not a subtype of parameter
    Foo.doit(consume b)
             ^
    Info:
    f3/main.pony:12:12: parameter type: String iso
      fun doit(s: String iso) =>
               ^
    f3/main.pony:19:14: argument type: String iso!
        Foo.doit(consume b)
                 ^
    f3/main.pony:7:34: String iso! is not a subtype of String iso: iso! is not a subtype of iso
      fun ref update(x: String iso): String iso =>
                                     ^

From the discussion previously on ! this error tells us that we are aliasing b. We can narrow it down by explicitly declaring the type of b:

let b: String iso = a.update(recover iso String end)

The error is due to update returning a String iso. We are consuming b and returning it as a String iso which then gets aliased when assigned to b in the main routine. Changing the return type to use hat resolves the issue. consume b returns the ephmeral type which is an object with no variable referencing it. It is safe to assign to a String iso so the change compiles:

class Box
  var a: String iso

  new create(x: String iso) =>
    a = consume x

  fun ref update(x: String iso): String iso^ =>
    let b = a = consume x
    consume b

primitive Foo
  fun doit(s: String iso) =>
    None

actor Main
  new create(env: Env) =>
    let a = Box(recover iso String end)
    let b = a.update(recover iso String end)
    Foo.doit(consume b)

Another approach would be to return a String iso but change doit to be a String tag (the type that can alias a String iso). This compiles but because doit now takes String tag it is limited in what it can do with the string. The approach of using an ephemeral type allows obtaining the mutable object from the Box.

Hat in parameters

Sometimes you'll see hat in parameter lists. The Array builtin has an init constructor that looks like:

new init(from: A^, len: USize)

This initializes an array so that all elements are the from value. To explore how this works, here's a smaller example that does something similar:

class Box[A]
  var a: A
  var b: A

  new create(x: A^) =>
    a = x
    b = x

Without the hat in A^ there is an error due to aliasing. We can't assign x to both a and b in case A is an iso. With the hat it compiles. The is because an epehemeral reference capability is a way of saying "a reference capability that, when aliased, results in the base reference capability". So a String iso^ can be assigned to a String iso, a String ref^ can be assigned to a String ref, etc. This means the generic class itself compiles but using it for a String iso will fail due to aliasing but it can be used for other reference capability types. Compare this to a plain x: A where the generic class itself won't compile since a String iso can't be assigned to another String iso due to aliasing.

Code demonstrating this is:

actor Main
  new create(env: Env) =>
    let a = Box[String iso](recover iso String end)
    let c = Box[String ref](recover ref String end)
    let e = Box[String val](recover val String end)

Arrow

The arrow syntax (or ->) is known as viewpoint adapter types and is related to viewpoint adaption.

Arrow in error messages

Viewpoint adaption defines what the reference capability of a field looks like to some caller based on the reference capability of the object the field is being read from. This is important to maintain the reference capability guarantees. A val object should not be able to access an iso field as iso or it breaks the constraints of val - it should be immutable but obtaining it as iso allows mutation of the field. There is a table in viewpoint adaption that shows what the mapping is.

An example of an error that can occur by ignoring viewpoint adaption is in the following code:

class Something
  var a: String iso

  new create() =>
    a = recover iso String end

  fun doit(s: String) =>
    a.append(s) 

actor Main
  new create(env: Env) =>
    let a = Something
    a.doit("hello")

The error here is calling append on a the a field in the doit method. By default methods have a receiver reference capability of box. Anything that happens inside the method cannot affect the state of the object. This is why you see methods that modify object fields start with fun ref - it's to change the receiver reference capability to something mutable. Even though the field a is iso and therefore mutable because we are inside a box method it appears as a non-mutable reference capability. The viewpoint adaption table shows that a box origin with an iso field gives a tag type. So a looks like a String tag within the method. The compiler gives:

Error:
v/main.pony:8:13: receiver type is not a subtype of target type
    a.append(s) 
            ^
    Info:
    v/main.pony:8:5: receiver type: this->String iso!
        a.append(s) 
        ^
    ny/ponyc/packages/builtin/string.pony:622:3: target type: String ref
      fun ref append(seq: ReadSeq[U8], offset: USize = 0, len: USize = -1)
      ^
    v/main.pony:2:10: String tag is not a subtype of String ref: tag is not a subtype of ref
      var a: String iso
             ^

The 'receiver type' of this->String iso! is an example of arrow usage. It's saying that an object of type String iso! (an alias to a String iso) as seen by an origin of this. The reference capability of this in a method is that of the receiver reference capability on the function - in this case box. So this->String iso! is String tag. That's why the last error description line refers to String tag.

The solution here is to change the reference capability for the method to something that allows mutation:

fun ref doit(s: String) =>

Arrow in type declarations

When writing generic code it's sometimes required to be explicit in what viewpoint adaption to use for generic types. Returning to the Box example used previously we'll make it generic and make it usable for any reference capability:

class Box[A]
  var a: A

  new create(x: A) =>
    a = consume x

  fun apply(): this->A! =>
    a

  fun ref update(x: A): A^ =>
    let b = a = consume x
    consume b

  fun clone(): Box[this->A!] =>
    Box[this->A!](a)

Notice the use of this->A! in the return type of apply. We want to return what is held in the Box. If it is a Box[String val] val then we can return a String val since it is immutable and the box is immutable. If it is a Box[String ref] val we still want to return a String val, not a String ref. The latter would allow modifying an immutable box. If it's a Box[String ref] ref then it's safe to return a String ref. This is what the arrow type handles for us. The this refers to the reference capability of the object. The A! refers to the field type - note that it is being aliased here so we want a type that can hold an alias to an A. The viewpoint adaption gives the resulting reference capability of the type.

Looking up the table of viewpoint adaption gives:

Box[String val] val => val->val => val => String val
Box[String ref] val => val->ref => val => String val
Box[String ref] ref => ref->ref => ref => String ref
Box[String iso] ref => ref->iso => iso => String iso
Box[String ref] iso => iso->ref => tag => String tag

That last one is interesting in that the Box[String ref] iso says that only one reference of the Box can exist. If we allow a String ref to be obtained from it then it breaks this condition since both the original reference to the box can modify the string and so can the returned reference. This is why the viewpoint adaption gives a String tag. A tag only allows identity operations so it's safe to have this type of alias of an iso.

Note that the table above gives the mapping for this->A. Because it's a this->A! it has to be a type that can hold an alias to the type of the table. So we have another mapping:

String val! => String val
String ref! => String ref
String iso! => String tag

In this way a Box[String iso] ref will give out a String tag - the only safe way of aliasing the original string in the box.

The other use of an arrow type in this example is in the clone function. This must do a shallow copy of the object. It returns a new Box holding a reference to the same value. Because we need to alias the value the same constraints as described for the apply method exist. We want to return a Box[this->A!] to ensure the value object for that box instance is a safe alias to the original. For a Box[String iso] ref this returns a Box[String tag] for example.

The following code can be used with the Box class above to test it:

primitive Foo
  fun doit(s: String tag) =>
    None

actor Main
  new create(env: Env) =>
    let a = Box[String iso](recover iso String end)
    let b = a.clone()
    Foo.doit(b())

    let c = Box[String ref](recover ref String end)
    let d = c.clone()
    Foo.doit(d())

    let e = Box[String val](recover val String end)
    let f = e.clone()
    Foo.doit(f())

A->B arrows

Arrow types don't need to always use this on the receiver side. They can use an explicit reference capability like box->A or they can use another parameterized type. Examples of this are in some of the library code:

class ArrayValues[A, B: Array[A] #read] is Iterator[B->A]

An ArrayValues is returned by the values method on Array. It's an iterator over the objects in the array. The B->A syntax means that the type of the generic argument to Iterator is of type "A as seen by B" using viewpoint adaption. It's not an iterator over A, it's an iterator over "A as seen by B". This allows iteration over arrays whether they are val or ref and produces a compatible type for the Iterator that works with both.

Conclusion

Most of the functionality described here is some of the more esotoric Pony functionality. It is mainly hit when using generics. The best current reference for generics is a video by Sylvan Clebsch for the virtual Pony users group - Writing Generic Code.

A good way to learn is to try some of the examples in this post and play around with them. Try aliasing, using different types, different reference capabilities and see what happens. The Pony library code, Array.pony for example, is a useful reference.

Closures in Pony

2016-03-15T11:00:00+13:00

Note 2017-08-01: Recent releases of Pony have changed syntax for lambda calls and partial function calls. This post has been updated to work with these changes as of Pony 0.16.1.

The Pony programming language has support for closures but the documentation hasn't caught up with changes to the implementation. This post describes some of the features of Pony closures with examples. These examples require the latest version of Pony from the github repository. I used commit e4f6f91d.

Lambda

Closures are functions combined with an environment mapping names to values. Pony has a {...} syntax that can be used to create them. It's possible to create a function that captures from the lexical scope and to create a function with no capturing at all.

The following example shows using a lambda that does not capture anything (note that this is an artificial example - the List type already has various mapping and fold functions on it):

use "collections"

actor Main
  new create(env:Env) =>
    let l = List[U32]
    l.push(10)
    l.push(20)
    l.push(30)
    l.push(40)
    let r = reduce(l, 0, {(a:U32,b:U32): U32 => a + b})
    env.out.print("Result: " + r.string())

  fun reduce(l: List[U32], acc: U32, f: {(U32, U32): U32} val): U32 =>
    try
      let acc' = f(acc, l.shift()?)
      reduce(l, acc', f)
    else
      acc
    end

The reduce function takes an anonymous function as a parameter, named f. This is is defined as {(U32, U32): U32}. This syntax means that it must take two U32 arguments and returns a U32. A U32 is a 32-bit unsigned integer.

The val is a reference capability annotation. It states that f is an immutable value. Since nothing inside f can be mutated it is safe for f to be shared with other actors. Lambda functions that do not close over other variables default to val as they cannot change anything outside of the function. We need to explicitly annotate the val as {...} declarations default to ref. A compile error would result without it due to passing a val object to a ref parameter.

Compiling and running produces the result 100 as expected:

$ ponyc example
$ ...
$ ./example1
  Result: 100

Lambda with environment

The following example closes over the env variable so that it can be accessed within the lambda to print the String contained in the List:

use "collections"

actor Main
  new create(env:Env) =>
    let l = List[String]
    l.push("hello")
    l.push("world")
    for_each(l, {(s:String)(env) => env.out.print(s)})

  fun for_each(l: List[String], f: {(String)}) =>
    try
      f(l.shift()?)
      for_each(l, f)
    end

Notice that the lambda has an additional set of parameters, the (env). This is an argument list of the variables that are being closed over. Variables listed there can be accessed from the body of the lambda. Pony requires you to be explicit about what gets captured vs many other languages that implicitly capture variables in scope. Variables can be renamed in this parameter list using the following syntax:

for_each(l, {(s:String)(myenv=env) => myenv.out.print(s)})

The lambda here returns None which is the default so it is left off the declaration {(String)}. This declaration requires a function that takes a single String argument and returns None. The return value is also left off the actual lambda expression. No reference capability annotations are required here as {...} defaults to ref and a lambda that closes over variables also defaults to ref.

Lambda modifying closed variables

A modification of the above example might be to keep a count of each time the lambda is called and display the count:

actor Main
  new create(env:Env) =>
    let l = List[String]
    l.push("hello")
    l.push("world")
    var count = U32(0)
    for_each(l, {ref(s:String)(env,count) =>
                    env.out.print(s)
                    count = count + 1})
    // Displays '0' as the count
    env.out.print("Count: " + count.string())

fun for_each(l: List[String], f: {ref(String)}) =>
  try
    f(l.shift()?)
    for_each(l, f)
  end

The main thing to note here is that both the lambda definition and the declaration have a ref prefixed to the argument list. This signifies a lambda that might mutate itself when called. The effect of this is that within the body of the lambda the receiver of method calls and field access (ie. the this of the lambda object) is a ref vs the default of box. A box receiver won't allow ref functions to be called and mutating requires a ref receiver.

There is an issue with this example as noted by the comment. The final count is displayed as zero. The assignment of count within the lambda changes the count field within the lambda object. The count within the lambda increments and could be displayed showing the increasing values. The count outside of this does not. There is no reference or pointer to the closed over variable. Indirection can be used to do this by using a one element array:

var count : Array[U32] = Array[U32].init(0, 1)
for_each(l, {ref(s:String)(env,count) =>
              try
                env.out.print(s)
                count(0)? = count(0)? + 1
              end})
try
  env.out.print("Count: " + count(0)?.string())
end

The array access is wrapped with try as it is a partial function and can fail. Another approach could be to move the act of counting into an Actor:

use "collections"

actor Counter
  var n: U32 = 0

  be increment() =>
    n = n + 1

  be print(env:Env) =>
    env.out.print("Count: " + n.string())

actor Main
  new create(env:Env) =>
    let l = List[String]
    l.push("hello")
    l.push("world")
    let counter = Counter
    for_each(l, {(s:String)(env,counter) =>
                  env.out.print(s)
                  counter.increment()})
    counter.print(env)

  fun for_each(l: List[String], f: {(String)}) =>
    try
      f(l.shift()?)
      for_each(l, f)
    end

Actors have the tag reference capability and are easier to pass around to other objects, including lambda.

The example here is contrived in that it can be done without modifying a captured variable. Sylvan produced the following approach, using the methods in the collections package:

use "collections"

actor Main
  new create(env:Env) =>
    let l = List[String]
    l.push("hello")
    l.push("world")

    let count = l.fold[U32](
      {(x: U32, s: String)(env): U32 =>
        env.out.print(s)
        x + 1}, 0)

    env.out.print("Count: " + count.string())

Object Literals

Object literals are a way to create objects inline without having to name a class or actor. They look like:

object
  let x = 10
  fun foo() =>
    ...do something...
end

Lambda's are actually syntactic sugar on top of object literals. A lambda expansion looks like:

// Lambda
{(s:String)(env) => env.out.print(s)}

// Expands to:
object
  var env:Env = env
  fun apply(s:String) =>
    env.out.print(s)
end

The apply method of an object is called when the () function call syntax is used. Keeping this syntactic transformation in mind can help solve errors that occur when using lambda. The example earlier where the count total didn't account for the increments in the lambda becomes obvious here. The transformation would be:

var count = U32(0)
for_each(l, object
              var env:Env = env
              var count:U32 = count
              fun ref apply(s:String) =>
                env.out.print(s)
                count = count + 1
            end)
env.out.print("Count: " + count.string())

Note the ref annotation in the apply method. This is what the {ref(...)} syntax results in. Without the ref in the {} syntax the syntactic expansion is fun apply(...). The default reference capability for fun in objects is box.

The object literal expansion helps show the difference between {(string)} ref and {ref(String))}. The first requires an object with the given reference capability to match the type. Although the object is a ref, the apply method is the default, a box. This means it cannot modify any fields in the object. In the case of a lambda it won't be able to modify the captured variables:

object ref
  fun apply(...)
end

To match the second type definition it requires an object where the apply method itself has the ref capability. This allows apply to modify fields of the object:

object
  fun ref apply(...)
end

Partial Application

Related to lambda is partial application. It allows supplying some arguments to a function (or constructor or behaviour) and returns something that allows supplying the other arguments later.

In cases where you would use a lambda to return a function that sets the value of some arguments you can use partial application instead. The following example creates a lambda that adds five to another number:

actor Main
  new create(env:Env) =>
    let add5 = {(a:U32): U32 => 5 + a}
    env.out.print(add5(10).string())
    env.out.print(add5(20).string())

With partial application this becomes:

actor Main
  new create(env:Env) =>
    let add5 = U32(5)~add()
    env.out.print(add5(10).string())
    env.out.print(add5(20).string())

The use of + is an alias for the add method on an object. In the example above the ~ operator represents partial application. We are binding the receiver of the add method to be the 32-bit unsigned value 5. The resulting object can be called with the remaining arguments.

Partial application allows binding any arguments, by position or by name. The tutorial goes into a lot of detail.

Accumulator Generator

Paul Graham has an accumulator generator problem with examples in various languages. The problem is defined as:

Write a function foo that takes a number n and returns a function that takes a number i, and returns n incremented by i.

A Pony implementation, using closures, could be:

actor Main
  fun foo(n:U32): {ref(U32): U32} =>
    var s: Array[U32] = Array[U32].init(n, 1)
    {ref(i:U32)(s): U32 =>
      try
        s(0)? = s(0)? + i
        s(0)?
      else
        0
      end}

  new create(env:Env) =>
    var f = foo(5)
    env.out.print(f(10).string())
    env.out.print(f(20).string())

This uses the one element array trick to enable modifying the captured variable due to the requirement that the number n is incremented. It works only for U32 rather than any number which is also part of the problem definition. Pony has generics which would allow solving this but I'll leave that as an exercise or a future post.

Cross compile Pony programs for Android

2015-12-17T19:00:00+13:00

Support for compiling Pony programs on ARM and 32-bit x86 landed recently. This allows compiling and running Pony on Raspberry Pi and other ARM devices. I was curious if it would be possible to compile Pony programs to run on Android and this post outlines how I got a "Hello World" example working.

The Pony compiler, ponyc, does not currently support cross compilation. It uses the C pre-processor to generate code for the platform it is running on. This has hardcoded assumptions for byte size (32 vs 64 bit) and processor support (ARM vs x86). Note that this is a proof of concept and hacks the compiler and runtime source to get things working. From this I hope to learn more elegant ways of supporting cross compiling.

Ponyc Android Cross Compiler

The first step was to build a version of ponyc that would generate Android compatible ARM code without any host platform specific code being included. I built ponyc for 32-bit x86, modified to not include any x86 specific code generation and to allow selecting the non-native LLVM backends. This ensures that the hard coded assumptions for the 32-bit size matches my target, 32-bit Android.

The changes for this are in the android_ponyc_cross branch of my github repository. The changes were:

Modify the Makefile to use 32-bit flags to the compiler.
Add some LLVM initialization to allow selection of non-native backends so ARM can be generated on x86 hosts.
Comment out some PLATFORM_IS_X86 preprocessor statements to prevent x86 specific code being generated.

For a real cross compiler these would be changed to be runtime selectable in some way. For the proof of concept it suffices to create a hardcoded compiler specific for this example.

For me it was necessary to build a version of LLVM for 32-bit as I'm on a 64-bit host. This was done by doing the following:

$ sudo apt-get install libicu-dev:i386 libncurses5-dev:i386 libxml2-dev:i386
$ tar xvf /tmp/llvm-3.6.2.src.tar.xz
$ cd llvm-3.6.2.src/tools
$ tar xvf /tmp/cfe-3.6.2.src.tar.xz
$ mv cfe-3.6.2.src clang
$ cd ..
$ mkdir build
$ cd build
$ cmake -DLLVM_BUILD_32_BITS=ON -DCMAKE_INSTALL_PREFIX=/tmp/llvm ..      
$ make
$ make install

Building the modified ponyc used these steps:

$ git clone -b android_ponyc_cross https://github.com/doublec/ponyc android_ponyc_cross
$ cd android_ponyc_cross
$ LLVM_CONFIG=/tmp/llvm/bin/llvm-config CXX="g++ -m32" make config=release ponyc

This generates a ponyc executable in the build/release directory.

Android compatible Pony runtime

An Android compatible libponyrt library is needed to link. The changes to build this are on the android_libponyrt branch. This must be built using an Android NDK standalone toolkit. A compatible standalone toolkit can be created with the following run from the NDK root directory:

$ ./build/tools/make-standalone-toolchain.sh --arch=arm \
     --platform=android-21 --install-dir=/tmp/stk21

Add the resulting installation directory to the PATH:

$ export PATH=/tmp/stk21/bin:$PATH

Make sure a recent ponyc compiler is on the PATH. This should not be the cross compiler built previously but a ponyc compiler for the host platform. Build the runtime library with:

$ git clone -b android_libponyrt https://github.com/doublec/ponyc android_libponyrt
$ cd android_libponyrt
$ CC=arm-linux-androideabi-gcc make config=release libponyrt

The resulting library is in the directory build/release/libponyrt.a.

Compiling to Android

With the above tasks complete it's now possible to build an Android compatible binary. I tested with a "Hello World" example:

actor Main
  new create(env:Env) =>
    env.out.print("Hello Android")

With that in a main.pony file in a hello directory, build with:

$ /tmp/android_ponyc_cross/build/release/ponyc --triple arm-linux-androideabi -rir hello
...ignore warnings about core-avx2 feature here...
$ llvm-as hello.ll
$ llc -mtriple=arm-linux-androideabi hello.bc -o hello.o -filetype=obj
$ arm-linux-androideabi-gcc -fPIE -pie hello.o -o hello1 -L/tmp/android_libponyrt/build/release/ -lponyrt

The first command instructs our cross compiler to generate code for Android and to only produce the LLVM assembly listing. This is compiled to bytecode with llvm-as and then to an object file with llc. The Android version of gcc is used to link with the Android version of libponyrt that was created earlier. The hello binary that is produced can be copied to an Android device (I used a Note 3 running Lollipop) and run:

$ adb push hello1 /data/local/tmp/
$ adb shell
$ cd /data/local/tmp
$ ./hello1
Hello Android

Conclusion

I haven't tested any other features running on Android yet but this is a promising start. Using the Pony FFI and JNI it is hopefluly possible to write native Android applications.

The steps I used for getting ponyc to generate LLVM instructions and using the LLVM tools to compile it were obtained from a gist by Darach Ennis. Similar steps would probably work on other LLVM compatible platforms.

C linkable libraries with Pony

2015-12-16T19:00:00+13:00

Note 2017-08-01: Recent releases of Pony have changed some of the details of interacting with C. This post has been updated to work with these changes as of Pony 0.16.1.

My quick look at Pony post covered how to use the FFI to call C code from a Pony program. It's also possible to compile Pony code to a C library that can be linked into a C program. This allows integrating Pony into existing C projects without having to convert the C project into a library to be called by Pony.

I've put a small example of how to do this on github at https://github.com/doublec/pony-clib-example.

Pony has a special type of actor that will result in a C compatible interface being generated. The syntax for this is actor@. The example in the project is:

actor@ Foo
  new create() =>
    None

  be hi() =>
    @printf[I32]("Hi\n".cstring())

This creates a C compatible actor called Foo. It has a constructor create and a behaviour hi. The constructor does nothing and only exists in the example to show how to call it from C. The hi behaviour calls the C function printf using the Pony FFI. With a file main.pony containing this code in a clib directory it can be built with:

$ ponyc -l clib
Building builtin -> packages/builtin
Building clib -> clib
Generating
Optimising
Writing ./clib.o
Archiving ./libclib.a

The -l switch to ponyc results in a static library being built instead of an executable. A libclib.a is generated containing the compiled Pony code. A clib.h is also generated containing the C function declarations for creating and interacting with any actor@ instances. For the Foo actor this looks like:

typedef struct Foo Foo;
Foo* Foo_Alloc();
None* Foo_tag_hi_o__send(Foo* self);
Foo* Foo_tag_create_o__send(Foo* self);

Pony has a runtime that needs to be initialized from C and a scheduler that needs to be started. The definitions for these runtime functions can be found in the ponyc source in libponyrt/pony.h. This needs to be included by the C program. A basic C driver for the example project is:

#include <stdio.h>
#include "clib.h"
#include "pony.h"

int main(int argc, char** argv) {
  pony_init(argc, argv);

  Foo* x = Foo_Alloc();
  Foo_tag_hi_o__send(x);
  Foo_tag_create_o__send(x);

  pony_start(true, true);
  return 0;
}

This sould be compiled and linked against libclib.a and libponyrt.a:

export PONYRT_INCLUDE=/path/to/ponyc/src/libponyrt/
export PONYRT_COMMON=/path/to/ponyc/src/common
export PONYRT_LIB=/path/to/ponyc/build/release/libponyrt.a

gcc -o test -I. -I $(PONYRT_INCLUDE) -I $(PONYRT_COMMON) \
    -g -rdynamic -mcx16 test.c libclib.a $(PONYRT_LIB) -lpthread -ldl

The C code needs to call pony_init to initialize the Pony runtime. It gets passed the standard C argc and argv arguments that main receives so it can handle any Pony runtime specific switches. After this any Pony actors can be allocated and methods or behaviours called on them. The order for actor creation is to call the _Alloc function to allocate the memory for the actor and then the constructor method. Pony names the constructor method based on the name in the Pony code with __send appended.

Actors are asynchronous so just like in Pony code behaviours aren't run immediately. They are queued for execution and will run when the scheduler is started. This is what pony_start does. The arguments passed to pony_start are a boolean indicating whether to block until all Pony actors have completed (by passing a false value) or to return immediately (by passing a true value). If the latter is done then the scheduler runs asynchronously. It can be stopped with a later call to pony_stop. The second parameter indicates whether to initialize Pony specific parts of the runtime (sockets and serialization). It's possible to continue calling Pony functions after the pony_start and before pony_stop. For example:

pony_init(argc, argv);

Foo* x = Foo_Alloc();
Foo_tag_hi_o__send(x);
Foo_tag_create_o__send(x);

pony_start(true, true);

Foo* y = Foo_Alloc();
Foo_tag_hi_o__send(y);
Foo_tag_create_o__send(y);

pony_stop();

In this snippet another actor is created after pony_start and behaviours are called on it. These are queued and run as expected. pony_stop blocks until all Pony actors have completed.

There are other Pony runtime functions in pony.h that allow allocating memory on the current actor heap, unscheduling an actor so that no behaviours will be run until rescheduled, making a C thread 'become' an actor so it can call Pony runtime functions, poll for messages on an unscheduled actor, etc. It's possible to allocate an actor, unschedule it, and then use a C thread to handle its message queue using pony_become. When you aren't handling messages to the unscheduled actor you can call functions to it from C with no race conditions.

None of this is currently documented and it will probably change as usage develops. In the meantime it's a useful feature for using Pony functionality in existing applications.

A quick look at the Pony Programming Language

2015-11-04T19:00:00+13:00

Pony is a new programming language described on their site as "an open-source, object-oriented, actor-model, capabilities-secure, high performance programming language."

It has some interesting features and is different enough to existing popular programming languages to make it a nice diversion to experiment with. Some features include:

lightweight actor based concurrency with M:N threading, mapping multiple language level threads to operating system threads.
strong static typing with generics
data-race free. The type system ensures at compile time that a concurrent program can never have data races.
deadlock free. There are no locking mechanisms exposed to the user so there are no deadlocks.
capabilities exposed to the type system to allow compile time enforcing of such things as objects that have no other references to it, immutable values, reference values, etc.
lightweight C FFI

This post is an outline of my initial experiments with the languages including pitfalls to be aware of.

Installing

Pony can be installed from git and run from the build directory:

$ git clone https://github.com/CausalityLtd/ponyc
$ cd ponyc
$ make config=release
$ export PATH=`pwd`/build/release:$PATH
$ ponyc --help

Run tests with:

$ make config=release test

Some of the Pony standard packages dynamically load shared libraries. If they're not installed this will be reflected in build failures during the tests. The required libraries on a Linux based machine are openssl and pcre2-8. To build Pony itself llvm version 3.6 needs to be installed. There is an llvm37 branch on github that works on Linux but is awaiting some llvm37 fixes before it is merged into master.

Pony can be installed in a default location, or using prefix to install it somewhere else:

$ make config=release prefix=/home/user/pony install

One catch is that running ponyc requires it to find the Pony runtime library libponyrt.a for linking purposes. This might not be found if installed somewhere that it doesn't expect. This can be resolved by setting the environment variable LIBRARY_PATH to the directory where libponyrt.a resides. I had to do this for the Nix Pony package.

Compiling Pony programs

A basic "Hello World" application looks like:

actor Main
  new create(env: Env) =>
    env.out.print("hello world")

Place this in a main.pony file in a directory and compile:

$ mkdir hello
$ cat >hello/main.pony
  actor Main
   new create(env: Env) =>
     env.out.print("hello world")
$ ponyc hello
$ ./hello1
hello world

ponyc requires a directory as an argument and it compiles the *.pony files in that directory. It generates an executable based on the directory name, with a number appended if needed to prevent a name clash with the directory. The program starts executing by creating a Main actor and passing it an Env object allowing access to command line arguments, standard input/output, etc. The Main actor can then create other actors or do whatever required for program execution.

Actors

Actors are the method of concurrency in Pony. An actor is like a normal object in that it can have state and methods. It can also have behaviours. A behaviour is a method that when called is executed asynchronously. It returns immediately and is queued to be run on an actor local queue. When the actor has nothing to do (not running an existing method or behaviour) it will pop the oldest queued behaviour and run that. An actor can only run one behaviour at a time - this means there needs to be no locking within the behaviour since access to actor local state is serialized. For this reason it's useful to think of an actor as a unit of sequential execution. Parallelism is achieved by utilising multiple actors.

To compare the difference between a standard object and an actor I'll use the following program:

class Logger
  let _env: Env
  let _prefix: String

  new create(env: Env, prefix: String) =>
    _env = env
    _prefix = prefix

  fun log(msg: String, delay: U32) =>
    @sleep[I32](delay)
    _env.out.print(_prefix + ": " + msg)

actor Main
  new create(env: Env) =>
    let l1 = Logger.create(env, "logger 1")
    let l2 = Logger.create(env, "logger 2")

    l1.log("one", 3)
    l2.log("two", 1)
    l1.log("three", 3)
    l2.log("four", 1)

This creates a class called Logger that on construction takes an Env to use to output log messages and a string prefix to prepend to a message. It has a log method that will log a message to standard output after sleeping for a number of seconds given by delay. The unusual syntax for the sleep call is the syntax for calling the sleep C function using the Pony FFI. I'll cover this later.

The Main actor creates two loggers and logs twice to each one with a different delay. As a standard object using class is not asynchronous running this will result in a delay of three seconds, outputting the first log line, a delay of one second, outputting the second line, a delay of three seconds, outputting the third line and finally a delay of one second, outputting the final line. Everything happens on the single Pony thread that runs the Main actor's create constructor. Pony runs this on a single operating system thread. Total elapsed time is the sum of the delays.

Compile and build with:

$ mkdir clogger
$ cat >clogger/main.pony
  ..contents of program above...
$ ponyc clogger
$ time ./clogger1
  logger 1: one
  logger 2: two
  logger 1: three
  logger 2: four

  real  0m8.093s
  user  0m0.116s
  sys   0m0.132s

Changing the Logger class to an actor and making the log method a behaviour will result in the logging happen asynchronously. The changes are:

actor Logger
  let _env: Env
  let _prefix: String

  new create(env: Env, prefix: String) =>
    _env = env
    _prefix = prefix

  be log(msg: String, delay: U32) =>
    @sleep[I32](delay)
    _env.out.print(_prefix + ": " + msg)

Nothing else in the program changes. I've just changed class to actor and fun to be. Now when the Main actor calls log it will add the behaviour call to the actor's queue and immediately return. Each Logger instance is running in its own Pony thread and will be mapped to an operating system thread if possible. On a multiple core machine this should mean each actor's behaviour is running on a different core.

Compiling and running gives:

$ mkdir alogger
$ cat >alogger/main.pony
  ..contents of program above...
$ ponyc alogger
$ time ./alogger1
  logger 2: two
  logger 2: four
  logger 1: one
  logger 1: three

  real  0m6.113s
  user  0m0.164s
  sys   0m0.084s

Notice that the total elapsed time is now six seconds. This is the sum of the delays in the calls to log in the first Logger instance. The second instance is running on another OS thread so executes in parallel. Each log call immediately returns and is queued to run. The delays on the second Logger instance are shorter so they appear first. They two log calls on the second Logger run sequentially as behaviours on a single actor instance are executed in order. The log calls for the first Logger instance run after their delay, again sequentially for the calls within that actor.

Capabilities

Pony uses reference capabilities to allow safe concurrent access to objects. In practice this means annotating types with a tag to indicate how 'sharable' an object is. For data to be passed to another actor it must be safe for that actor to use without data races. Reference capabilities allow enforcing this at compile time. There are defaults for most types so you don't need to annotate everything. Notice that none of the examples I've done so far use any capability annotations. I'll go through a few examples here but won't be exhaustive. The Pony tutorial has coverage of the combinations and defaults.

val and ref

A val capability is for value types. They are immutable and therefore anyone can read from them at any time. val objects can be passed to actors and used concurrently. Primitives like U32 are val by default. This is why none of the primitive arguments to behaviours in the previous examples needed annotation.

A ref capability is for references to mutable data structures. They can be read from and written to and have multiple aliases to it. You can't share these with other actors as that would potentially cause data races. Classes are ref by default.

This is an example of passing a val to another actor:

actor Doer
  be do1(n: U32) =>
    None

actor Main
  new create(env: Env) =>
    let a = Doer.create()
    let n: U32 = 5
    a.do1(n)

As U32 is a primitive it defaults to a val reference capability. It is immutable and can be read by anyone at any time so this compiles without problem. This example fails to compile however:

class Foo
  let n: U32 = 5

actor Doer
  be do1(n: Foo) =>
    None

actor Main
  new create(env: Env) =>
    let a = Doer.create()
    let b = Foo.create()
    a.do1(b)

The error is:

main.pony:5:13: this parameter must be sendable (iso, val or tag)
  be do1(n: Foo) =>
            ^

class defaults to the ref capability which can be read, written and aliased. It can't be used to send to another actor as there's no guarantee that it won't be modifed by any other object holding a reference to it. The iso and tag capabilities mentioned in the error message are other capability types.

iso is for single references to data structures that can be read and written too. The type system guarantees that only one reference exists to the object. It is short for 'isolated'.

tag is for identification only. Objects of capability tag cannot be read from or written too. They can only be used for object identity or, if they are an Actor, calling behaviours on them. Actors default to tag capabilities. Calling behaviours is safe as behaviour running is serialized for the actor instance and they don't return data.

To get the previous example to work we can force the Foo object to be of type val if it can be immutable:

class Foo 
  let n: U32 = 5

actor Doer
  be do1(n: Foo val) =>
    None

actor Main
  new create(env: Env) =>
    let a = Doer.create()
    let b: Foo val = Foo.create()
    a.do1(b)

ref and iso

Let's modify the example so we can change the value of the Foo object to demonstrate moving a mutable reference from one actor to another:

class Foo
  var n: U32 = 5

  fun ref set(m: U32) =>
    n = m

  fun print(env: Env) =>
    env.out.print(n.string())

actor Doer
  be do1(env:Env, n: Foo iso) =>
    n.print(env)

actor Main
  new create(env: Env) =>
    let a = Doer.create()
    let b = Foo.create()
    a.do1(env, b)

In this example the do1 behaviour now requires an iso reference capability. As mentioned previously, iso means only one reference to the object exists therefore it is safe to read and write. But where we create the instance of Foo we have a reference to it in the variable b. Passing it as an argument to do1 effectively aliases it. The compile time error is:

main.pony:18:16: argument not a subtype of parameter
    a.do1(env, b)
               ^
main.pony:11:19: parameter type: Foo iso
  be do1(env:Env, n: Foo iso) =>

main.pony:18:16: argument type: Foo iso!
a.do1(env, b)
           ^

This error states that do1 requires a Foo iso parameter whereas it is being passed a Foo iso!. The ! at the end means that it is an alias to another variable. Even though class objects are ref by default, Pony has inferred the capability for b as iso as we didn't declare a type for b and we are passing it to a function that wants an iso. However as it has an alias it can't be used as an iso therefore it's an error.

One way of avoiding the aliasing is to pass the result of the create call directly:

actor Main
  new create(env: Env) =>
    let a = Doer.create()
    a.do1(env, Foo.create())

There is no alias here so it compiles fine.

If we do want to have an initial reference to it, say to set a value first, we can tell the type system that we are consuming the existing reference and will no longer use it. This is what the consume keyword is for:

actor Main
  new create(env: Env) =>
    let a = Doer.create()
    let b = Foo.create()
    b.set(42)
    a.do1(env, consume b)
    // b.set(0)

This now compiles. Uncommenting out the use of b after the do1 call will be a compile error as we've consumed b and it no longer exists. In this case the error owuld be:

main.pony:20:5: can't use a consumed local in an expression
    b.set(0)
    ^
main.pony:20:6: invalid left hand side
    b.set(0)

consume is more often used for passing iso objects around. To pass it to another object you need to consume the existing reference to it. This becomes problematic if you are consuming a field of an object. Modifying the example so that the Foo is stored as a field of Main shows the problem:

actor Main
  var b: Foo iso = Foo.create()

  new create(env: Env) =>
    let a = Doer.create()
    b.set(42)
    a.do1(env, consume b)

The error is:

main.pony:20:16: consume must take 'this', a local, or a parameter
    a.do1(env, consume b)
               ^

b can't be consumed as it's a field of Main. It can't be left consumed - it must have a valid Foo iso object stored in it. In Pony assignment returns the old value of the variable being assigned too. This allows assigning a new value to the field and returning the old value in one operation and avoiding leaving the field in an invalid state:

new create(env: Env) =>
  let a = Doer.create()
  b.set(42)
  a.do1(env, b = Foo.create())

b gets a new value of a new instance of Foo and do1 gets passed the old value.

There's a lot more to capabilities and the capabilities section of the tutorial covers a lot. Although there are sane defaults it feels like that 'capability tutorials' will be the Pony equivalent of 'Monad tutorials' in other languages for a while. When I first was learning ATS I spent a lot of time floundering with function annotations to get things to compile, trying random changes, until I learnt how it worked. I'm probably at that stage with capabilities at the moment and I hope it becomes clearer as I write more Pony programs.

Pattern Matching

Pony has many of the concepts of most modern functional programming languages. Matching on values is allowed:

let x: U32 = 2
match x
  | 1 => "one"
  | 2 => "two"
else
  "3"
end

Union types with capturing:

type Data is (U32 | String | None)
....
match x
| None => "None"
| 1 => "one"
| let u: U32 => "A number that is not one: " + u.string()
| let s: String => "A string: " + s
end

Enumerations are a bit verbose in that you have to use primitive to define each variant of the enumeration first:

primitive Red
primitive Blue
primitive Green

type Colour is (Red | Blue | Green)
...
let x: Colour = Red
match x
| Red => "Red"
| Blue => "Blue"
| Green => "Green"
end

C FFI

Pony has an easy to use C FFI. I showed an example of this previously:

@sleep[I32](delay)

The @ signifies that this is a C FFI function call. The type in the backets is the return type of the C function call. The types of the arguments must match what the actual C function expects. Errors here will crash the program. Pony allows specifying the type of an FFI function in advance so argument types are checked. For sleep it would be:

use @sleep[I32](n: U32)
...
@sleep(10)

Note that it's no longer necessary to specify the return type at the call point as it's already been defined in the declaration.

If the C function is part of a library already linked into the Pony executable then there is no need use a statement to define the library file to link against. sleep is part of libc so it isn't needed. In the cases where you need to link against a specific library then the use statement is used in this manner:

use "lib:foo"

The addressof keyword is used to pass pointers to C code. It can be used for passing out parameters of primitives types:

var n: U32 = 0
@dosomething[None](addressof n)
env.out.print("Result: " + n.string())

Callbacks

The FFI allows passing Pony functions to C for the C code to later call back. The syntax for this looks like:

let foo = Foo.create()
@callmeback[None](addressof foo.method, foo)

Calling C code example

A working example for the following C function in a cbffi.c file:

void do_callback(void (*func)(void* this, char* s), void* this) {
    func(this, "hello world");
}

The Pony code to use this is:

use "lib:cbffi"

class Foo
  let prefix: String
  let env: Env

  new create(e: Env, p: String) =>
    prefix = p
    env = e

  fun display(msg: Pointer[U8]) =>
    env.out.print(prefix + ":" + String.copy_cstring(msg))

actor Main
  new create(env: Env) =>
    let foo = Foo.create(env, "From Pony")
    @do_callback[None](addressof foo.display, foo)

Note that the display function takes a Pointer[U8] as an argument. Pointer[U8] is a generic type with U8 being the parameter. In this case it is the C string that the C function passes. Pony String types are an object with fields so C doesn't pass it directly. The String type has a couple of constructor functions that take Pointer[U8] as input and return a Pony String - the one used here, copy_cstring, makes a copy of the C string passed in.

Compile with:

$ mkdir cb
$ cat >cb/main.pony
  ...Pony code...
$ cat >cb/cbffi.c
  ...C code...
$ gcc -fPIC -shared -o libcbffi.so cb/cbffi.c
$ LIBRARY_PATH=. ponyc cb
$ LD_LIBRARY_PATH=. ./cb1
  From Pony:hello world

Here LIBRARY_PATH is set to find the shared library during compiling and linking. To run the generated executable LD_LIBRARY_PATH is used to find the shared library at runtime.

It's also possible to link against static C libraries:

$ rm libcbffi.so
$ gcc -c -o libcbffi.o cb/cbffi.c
$ ar -q libcbffi.a libcbffi.o
$ LIBRARY_PATH=. ponyc cb
$ ./cb1
  From Pony:hello world

Things to look out for

While writing Pony code I came across a couple of things to be aware of. Each actor has their own garbage collector but it runs only between behaviour calls. If a behaviour runs for a long time, never calling another actor behaviour, then it can be a while before garbage is collected. An example of where this can happen is a simple Main actor where everything is done in the default constructor and never calls another actor. Benchmarks can be an example here. No GC will occur and you can get an OOM (Out of Memory) situation.

Another is that there is no backpressure handling for behaviour calls on an actor. The message queues are unbounded so if a producer sends messages to an actor at a faster rate than it processes them then it will eventually OOM. This can occur if you have the message sender tied to an external process. For example a TCP listener that uses sockets and translates the data to a message to an actor. If the external users of the TCP interface (a webserver for example) are sending data faster than the actor handling the messages then OOM will occur. Slides from the Pony developers indicates that backpressure is on their radar to look at.

As usual with a new programming language there is a lack of libraries and library documentation. Expect to look through the Pony source code to find examples of how to do things. The tutorial is great though - even though parts are incomplete - and is on github.

There is a --docs command line argument that can be used to parse docstrings in Pony libraries and produce documentation in markdown format. For example:

$ cd packages
$ ponyc --docs collections
$ ls collections-docs/

Conclusion

This has only been a quick overview of some features of Pony. There's more too it. Some places to get more Pony information:

Pony website
Tutorial
/r/ponylang
#ponylang on irc.freenode.net
Mailing List
Online Sandbox to try Pony in a browser

Bluish Coder: pony

Reference Capabilities, Consume and Recover in Pony

tag - opaque reference

val - immutable and sharable

ref - readable, writable but not sharable

iso - readable, writable uniquely

consume - I don't want this alias

Converting capabilities

recover - restricted alias conversion

box - allows use of val or ref

trn - writeable uniquely, consumable to immutable

Capability Subtyping

Viewpoint Adaption

Miscellaneous things

Conclusion

Borrowing in Pony

Exploring actors in Pony

Behaviours

tag reference capability

Simulating return values

Promises

Sendable objects

Blocking operations

Causal Messaging

Garbage Collection

Bang, Hat and Arrow in Pony

Bang

Bang in errors

Bang in generics

Hat

Hat in parameters

Arrow

Arrow in error messages

Arrow in type declarations

A->B arrows

Conclusion

Closures in Pony

Lambda

Lambda with environment

Lambda modifying closed variables

Object Literals

Partial Application

Accumulator Generator

Further reading

Cross compile Pony programs for Android

Ponyc Android Cross Compiler

Android compatible Pony runtime

Compiling to Android

Conclusion

C linkable libraries with Pony

A quick look at the Pony Programming Language

Installing

Compiling Pony programs

Actors

Capabilities

val and ref

ref and iso

Pattern Matching

C FFI

Callbacks

Calling C code example

Things to look out for

Conclusion