Differences

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

--- at:tutorial:appendix [2008/07/10 15:53] – added tvcutsem
+++ at:tutorial:appendix [2008/07/10 16:24] – * tvcutsem
@@ Line 392: / Line 392: @@
 === 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 ''/.at.lang.futures'' provides support for futures. Futures have already been described as part of the [[:at:tutorial:actors#futures|concurrency]] section in the tutorial.
 The module exports the type tags ''OnewayMessage'', ''FutureMessage'' and ''Due'':
@@ Line 424: / Line 424: @@
 === Multifutures ===
-The module ''/.at.lang.multifutures'' provides support for 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 is constructed as follows:
+<code>
+def [mf, resolver] := makeMultiFuture(n, timeout);
+</code>
+The parameter ''n'' indicates the maximum number of values/exceptions with which the future can be resolved/ruined. If ''n'' is ''nil'', the multifuture is unbounded. The timeout parameter is optional. If not nil, it is a timeout period in milliseconds that causes the multifuture to //automatically// become fully resolved after the provided timeout. Once fully resolved, a multifuture will not accept any new values/exceptions, even if it has not reached its "upper bound" ''n'' yet.
+A multifuture accepts the following listeners:
+<code>
+whenEach: multiFuture becomes: { |val| ... }
+</code>
+The above 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>
+The above listener is invoked if all results have been gathered (only possible if the maximum number of results is known) or when the ''timeout'' period associated with the future has elapsed. ''values'' refers to a table of all resolved values. 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 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 ====
+The module ''/.at.lang.dynvars'' provides support for defining and using 'Dynamic Variables'. Dynamic variables 'simulate' dynamically scoped variables and are often used to parameterize large parts of code. For example, the 'current output stream'. A dynamic variable has the advantage over a simple global variable that it can only be assigned a value for the extent of a block of code.
+A dynamic variable can be defined as follows:
+<code>
+def name := dynamicVariable: initialValue;
+</code>
+It can be read as follows:
+<code>
+?name or name.value
+</code>
+It can be assigned only within a limited dynamic scope, as follows:
+<code>
+with: name is: newval do: { code }
+// or
+name.is: newval in: { code }
+</code>
+When ''code'' terminates (either normally or via an exception), the dynamic variable is automatically reset to its previous value.
+By convention, we prefix the names of dynamic variables with a ''d'', e.g. ''dTimeoutPeriod''. This makes it easier to remember to access these variables by means of ''?'' or ''.value''.
+You can find more usage examples of dynamic variables in the unit test included in the file ''at/lang/dynvars.at''.
 ==== Ambient References ====
+Ambient references are defined in the module ''/.at.lang.ambientrefs'' . An ambient reference is a special kind of far reference which refers to an ever-changing collection of objects of a certain type. For example:
+<code>
+import /.at.lang.ambientrefs;
+deftype Printer;
+def printers := ambient: Printer;
+</code>
+In the above code, ''printers'' refers to all nearby objects exported by means of  the ''Printer'' type tag. An more in-depth explanation of ambient references can be found on the [[:research:ambientrefs|research page of ambient references]].
+Ambient references ship with two so-called "implementation modules": the module ''/.at.ambient.ar_extensional_impl'' and the module ''/.at.m2mi.ar_intensional_impl''. By default, the extensional implementation is used, but this can be changed by passing the desired implementation module as a parameter to the ''/.at.lang.ambientrefs'' module.
 ==== Structural Types ====
 ==== Traits ====