Differences

This shows you the differences between two versions of the page.

--- at:tutorial:appendix [2008/07/10 14:51] – added tvcutsem
+++ at:tutorial:appendix [2008/07/10 16:02] – added tvcutsem
@@ Line 261: / Line 261: @@
 join(txt)
-// return a range [start,stop] represented as a list
+// drop the first n elements from the list
-select(start, stop)
+tail(n)
 // prepend an element to the list
@@ Line 293: / Line 293: @@
 The file ''at/collections/list.at'' contains a unit test that further illustrates the usage of the list datastructure.
+===== Top-level functions =====
+The file ''at/init/init.at'' shipped with the AmbientTalk/2 system library contains the code that is evaluated on startup within //every// actor created in the system. Because the definitions are evaluated in every actor's top-level scope, these  definitions will be globally visible in every file. Below, we describe the standard functionality provided by AmbientTalk/2's default ''init'' file.
+==== Asynchronous control structures ====
+The ''init'' file defines a number of useful control structures that operate asynchronously.
+''loop:'' defines an infinite asynchronous loop. That is, the block closure is executed, then asynchronously applied again:
+<code>
+loop: {
+  ...
+}
+</code>
+An ''if''-test on a future for a boolean:
+<code>
+whenTrue: booleanFuture then: { ... } else: { ... }
+</code>
+Asynchronous while loop over future-type conditional:
+<code>
+asLongAs: { /* asynchronous computation returning a future */ } do: { ... }
+</code>
+==== Mobile code ====
+The function ''script:carrying:'' can be used to define a "pass-by-copy" closure, as follows:
+<code>
+def mobileAdder(x) {
+  script: { |n| x + n } carrying: [`x]
+}
+</code>
+A call to ''mobileAdder(5)'' returns a closure which, when applied to a number, returns that number incremented with 5. Unlike regular closures, which are pass-by-far-reference when passing them to another actor, the above closure is pass-by-copy. The result is that a remote actor can apply the closure synchronously. The catch is that for this to work, the closure must specifically list all of its lexically free variables in the ''carrying:'' parameter. These variables will be copied along with the closure when it is parameter-passed.
+The constructor function ''isolate:passAs:'' allows you to define an isolate object with a custom serialization strategy. For example,
+<code>
+def foo := 42;
+def i := isolate: {
+  ...
+} passAs: { |foo|
+  /.some.Object.new(foo);
+}
+</code>
+The above code defines an isolate object ''i'' which, when passed between actors, becomes a ''some.Object'' on the other side. Note that state (''foo'' in the example) can be transferred as usual via the parameter list of the closure.
+===== Custom Exceptions =====
+The module ''/.at.exceptions'' defines a number of auxiliary methods which can be used to define one's own custom exceptions. Here is how to define a custom exception ''FooException''. First, define a new type tag with which clients of your code can catch the exception:
+<code>
+deftype FooException;
+</code>
+Next, define a prototype exception object using the ''createException'' function exported by the exception module. As a convention, an exception prototype object is prefixed with ''X'':
+<code>
+def XFooException := createException(FooException);
+</code>
+''XFooException'' is now bound to an object which is tagged with the given type tag, and which implements two methods: ''stackTrace'', which returns an AmbientTalk stack trace for the exception, and ''message'', which returns a string indicating what went wrong. The object also has a constructor taking a new message as an argument. You can now raise your custom exception as follows:
+<code>
+raise: XFooException.new("reason for what went wrong");
+</code>
+If your custom exception requires additional state, you can define it as an extension of the prototype exception. If you define a custom constructor, do not forget to initialise the parent object, as follows:
+<code>
+deftype IndexOutOfBounds;
+def XIndexOutOfBounds := createException(IndexOutOfBounds) with: {
+  def min;
+  def max;
+  def idx;
+  def init(min, max, idx) {
+    super^init("Index out of bounds: given " + idx + " allowed: [" + min + "," + max + "]");
+    self.min := min;
+    self.max := max;
+    self.idx := idx;
+  };
+}
+</code>
+The exception module also exports an auxiliary function ''error(msg)'' which can be used to raise a "quick and dirty" runtime exception with a given message. It also exports the prototypes of a number of standard exceptions that can be raised by the language runtime itself.
+===== Language Extensions =====
+The files in the ''at/lang'' directory define custom language features which mostly use AmbientTalk/2's reflective facilities to extend the language.
+==== Futures and Multifutures ====
+=== Futures ===
+The module ''/.at.lang.futures'' provides support for futures. Futures have already been described as part of the [[concurreny|concurrency]] section in the tutorial.
+The module exports the type tags ''OnewayMessage'', ''FutureMessage'' and ''Due'':
+  * Tagging an asynchronous message with ''FutureMessage'' will attach a future to the message.
+  * Tagging a message with ''OnewayMessage'' ensures no future will ever be attached to the message.
+  * Tagging a message with ''@Due(timeout)'' associates a future with the message that is automatically ruined with a ''TimeoutException'' after the given ''timeout'' period (in milliseconds) has elapsed.
+Messages can be automatically associated with a future by invoking the ''enableFutures()'' function, which enables futures for all messages, except those tagged as a ''OnewayMessage''.
+The futures module also exports the function ''when:becomes:'' to await the resolution of a future, and auxiliary ''when:becomes:catch:using:'' functions.
+Futures can also be created and resolved manually:
+<code>
+import /.at.lang.futures;
+def [fut, res] := makeFuture();
+when: someAsynchronousComputation() becomes: { |value|
+  res.resolve(value); // resolve the future manually
+}
+fut // return the future to a client
+</code>
+Finally, the futures module also provides some auxiliary functions, of which ''group:'' is often a very useful one. The ''group:'' construct groups a table of futures into a single future which is resolved with a table of values or ruined with an exception:
+<code>
+when: (group: [ a<-m(), b<-n() ]) becomes: { |values|
+  def [aResult, bResult] := values;
+  ...
+}
+</code>
+=== Multifutures ===
+The module ''/.at.lang.multifutures'' provides support for multifutures. A multifuture is a future that can be resolved multiple times. We distinguish between 'bounded multifutures', which can be resolved up to a maximum number and 'unbounded multifutures' which have no upper bound. A multifuture accepts  the following listeners:
+<code>
+whenEach: multiFuture becomes: { |val| ... }
+</code>
+This listener is invoked whenever the future is resolved with a new value. Its code can thus be executed multiple times.
+<code>
+whenAll: multiFuture resolved: { |values|
+  ...
+} ruined: { |exceptions| ... }
+</code>
+This listener invoked if all results have been gathered (only possible if the maximum number of results is known). If there are no exceptions, only the first code block is triggered. If there are only exceptions, the first block is still invoked with an empty value table.
+Note the following properties of multifutures:
+  * It is allowed to register a whenAll:resolved:ruined: listener an 'unbounded' multifuture. However, for such multifutures, this listener will only trigger if a timeout was specified during the multifuture's creation. The listener is invoked upon timeout, and later incoming results are discarded.
+  * As with futures, it is legal to send asynchronous messages to the multifuture, which are in turn propagated to all resolved values. If some values are ruined, asynchronous messages containing a multifuture are ruined. Hence, exceptions only propagate through a pipeline of multifutures.
+  * When a multifuture A is resolved with a multifuture B, all of B's eventual values/exceptions become values/exceptions of A.
+  * A whenEach:becomes: observer automatically returns a multifuture itself. This multifuture has the same arity as the original and is resolved/ruined with the return values of the multiple invocations of the becomes: or catch: closures.
+  * Like with futures, multifutures can be explicitly created, e.g.:
+<code>def [ multifut, resolver ] := makeMultiFuture(upperBound);</code>
+  * Multifutures can be attached to messages by annotating an asynchronous message with the @Gather(n) type tag.
+  * Adding a when:becomes: listener on a multifuture is allowed but only triggers for the first value/exception of the multifuture. This allows multifutures to be used wherever regular futures are expected.
+The multifutures module also exports an abstraction known as a "multireference". The expression ''multiref: [ ref1, ref2,... ]'', where ''refi'' are far references, returns a multireference. Any message sent to a multireference is sent to all constituent references, and a multifuture is returned which can trap the results.
+When the message sent to a multireference is annotated with @Due(t), the timeout is applied to the implicit multifuture, causing whenAll observers to trigger automatically. Note that the implicit multifuture of a multireference is bounded, so whenAll observers trigger automatically when all replies have been received.
+==== Dynamic Variables ====
+==== Ambient References ====
+==== Structural Types ====
+==== Traits ====