1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188

== Introduction ==

The Actor model is a model of concurrent computation  for distributed  systems.
An actor system consists of a number of concurrent and autonomous entities 
called actors. An actor has its own thread of control and state and is the 
unit of concurrency in the actor model. The state of actor is encapsulated 
and is not shared. Actors communicate using asynchronous message passing. 
Each actor updates its own local state by processing messages that it receives 
in its mailbox.  

Dart is the Google’s new language for web programming which features Isolates. 
Isolates provide a message passing model for programming in a non-shared memory 
setting. Here, we have an Actor framework developed on top of isolates as an 
alternative to using isolates directly. The goals of this framework are:

1- Easier concurrent programming in Dart via a familiar syntax inspired by Scala
and Erlang
2- Cheap creation of lightweight concurrent entities (actors) for responsiveness
3- Providing an API for accessing DOM from within a remote isolate


== Getting Started ==

An actor is defined by a class. It is required that this class extends the 
"Actor" class. The Actor class handles all the mechanics for sending and serving
messages and creating new actors. 

class HelloWorld extends Actor {
  HelloWorld() : super() {
    // ...
  }
}

Message handlers are defined inside the constructor's body.

class HelloWorld extends Actor {
  HelloWorld() : super() {
    
    // a message handler for "say hello" message  
    on["say hello"] = (String who) {
      ui.send("print", ["Hello $who!"]);
    };

    // a message handler for "say goodbye" message  
    on["say goodbye"] = (String who) {
      ui.send("print", ["Bye $who!"]);
    };

  }
}

Every actor has access to the 'ui' actor for printing on the console. One can 
print something on the console by sending "print" message to the ui actor:

  ui.print("A string");
  
Note that the print function is only a syntactic sugar for:

  ui.send("print", ["A string"]);


== Actor Discovery and Message Passing == 

No one can get a reference to an actor object. Actors are only accessible 
through their identity which can be used to send messages to the actor. 
How to send a message to an actor using its id?

  id.send("message name", [parameters]);
  
Running on the dart VM, parameters can be everything but closures. 

In order to become known to other actors, one can send its own id to them. An 
actor can access its own id using 'me' and can send it as a parameter.

  anotherActorId.send("contact me", [me]);   

One can only send a message to self using 'me':

  me.send("message to self", [parameters]);


== Creating Actors ==

ActorManager is responsible for creating actors. The first actor is created by 
actor manager from the main function of the application. For instance, for the
HelloWorld example, the main functions looks like the following:

main() {
  ActorManager manager = new ActorManager(1);
  manager.create(const HelloWorldFactory(), 
                  "say hello", ["World"]);
}

class HelloWorldFactory implements ActorFactory {
  const HelloWorldFactory();
  Actor create() => new HelloWorld();
}

Let's step through the main function. The following line will create an actor 
manager:

  ActorManager manager = new ActorManager(1);

The parameter sent to the constructor is the number of background isolates used
to schedule actors. In the above example it is one.

The next line will ask actor manager to create an actor using the specified 
factory object: 

  manager.create(const HelloWorldFactory(), 

The second and third parameters to the create function are the initial message 
and parameters that must be sent to the actor upon creation: 

  manager.create(const HelloWorldFactory(), 
                  "say hello", ["World"]);


Because of the lack of reflection (at the time of writing the framework) in
Dart, there should be an actor factory for each actor. 

An actor creates other actor by calling a create function. This function is 
defined in the "Actor" class and it has the same parameters as mentioned above.


== Request and Response ==

In order to get a response back for a message sent to another actor, you can use
a Reply object. The Reply object encapsulates the way a response should be sent
back to an actor. For instance, in the following example a client actor needs 
the fibonacci value of 100. It sends a message ("fibonacci") to a calculator 
actor and includes the number and a Reply object. Reply object takes two 
parameters. The first one indicates to whom the message must be sent and the 
second one indicates what message must be used to send the response back. 

///// Client Actor

on["some message"] = () {
  num n = 100;
  calculatorActor
    .send("fibonacci", 
      [n, new Reply(me, "fib-result")]);
};

on["fib-result"] = (num fibOfN) {
  ...
};

///// Calculator Actor

on["fibonacci"] = (num n, Reply reply) {
  reply.response([fib(n)]);
};

In the above example the, client must have a named message handler, 
"fib-result", in order to handle the result. One can use messageback to create 
an unnamed message handler. 


///// Client Actor

on["some message"] = () {
  num n = 100;
  calculatorActor
    .send("fibonacci", 
      [n, 
       messageback((num fibOfN) {
         ...
       };
       )]);
};


== Programming with Actors ==

When you are programming with actors, you can either program for web or 
terminal. If you are programming for web you will need to import 
'actors-web.dart' from core. You also will need to have a version of browser in 
which Dart VM is enabled. In case you only want to write a console application, 
you will need to import 'actors-term.dart' from core.  


== Known Issues ==

The current version of this framework does not work with frog and/or dartc.
Applications written using this framework run with Dart VM (command line or a
Dart enabled browser).