Ambient-Oriented Programming

User Tools

Site Tools

Trace:
at:tutorial:appendix

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
at:tutorial:appendix [2008/07/10 16:43] – added tvcutsemat:tutorial:appendix [2009/01/29 21:56] – * elisag
Line 1: Line 1:
-====== Appendix ======+====== Appendix: Libraries ======
  
 In the appendix, we explain useful libraries available to the AmbientTalk/2 programmer. These libraries provide abstractions ranging from traditional, established "collections" up to newly researched language constructs, such as "ambient references". In the appendix, we explain useful libraries available to the AmbientTalk/2 programmer. These libraries provide abstractions ranging from traditional, established "collections" up to newly researched language constructs, such as "ambient references".
Line 82: Line 82:
  
 It is also possible to use ''makeFuture()'' to create a fresh future explicitly within the unit test method, and to use the returned resolver to resolve the future at the appropriate time. It is also possible to use ''makeFuture()'' to create a fresh future explicitly within the unit test method, and to use the returned resolver to resolve the future at the appropriate time.
 +
 +<note tip>
 +See the [[distribution#take_offline_remote_objects|distributed programming]] chapter for details about how to simulate network disconnections in distributed unit tests.
 +</note>
  
 ==== Test Suites ==== ==== Test Suites ====
Line 462: Line 466:
  
 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. 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.
 +
 +==== Leased Object References ====
 +
 +The module ''/.at.lang.leasedrefs'' provides support for leased object references. Leased object references have already been described as part of the [[:at:tutorial:distribution#dealing_with_permanent_failures|distributed programing]] section in the tutorial.
 +
 +<note>
 +The implementation of leased object references actually consists of two files: ''/.at.lang.leasedrefs'' and ''/at.lang.leasedrefstrait''. ''leasedrefstrait'' module implements the common behaviour to the different types of leased references. This module is imported in the ''leasedrefs'' module which provides the public API for creating and managing leased object references.
 +</note>
 +
 +The ''leasedrefs'' module exports language constructs to create three different types of leased object references:
 +  * ''lease:for:''returns a leased reference that remains valid for the indicated time interval.
 +  * ''renewOnCallLease:for:'' returns a leased reference that it is automatically renewed each time the remote object receives a message with the specified time interval.
 +  * ''singleCallLease:for:'' returns a leased reference that remains valid for only a single method call on the remote object.
 +
 +Variations of these constructs are also provided to allow developers to specify the renewal time interval in renew-on-call leased references and the name(s) of the method(s) which expires a single-call leased reference.
 +
 +The ''leasedrefs'' module also provides the following constructs to explicit manage the lifetime of leased references:
 +
 +<code>
 +renew: leasedRef for: interval;
 +revoke: leasedRef;
 +leaseTimeLeft: leasedRef;
 +</code>
 +
 +''when:expired'' construct is provided to schedule clean-up actions with a leased reference upon its expiration.
 +
 +Finally, the ''leasedrefs'' module exports support primitives to manipulate time intervals (i.e. ''minutes'', ''seconds'', ''millisecs'') so that developers do not need to explicitly import the timer module to use leased references.
 +
 +
 +
  
 ==== Dynamic Variables ==== ==== Dynamic Variables ====
Line 576: Line 610:
  
 ==== Timing Utilities ==== ==== Timing Utilities ====
 +
 +The module ''/.at.support.timer'' provides utility functions to schedule code for execution at a later point in time. Its most useful control construct is the following:
 +
 +<code>
 +def subscription := when: timeoutPeriod elapsed: {
 +  ...
 +}
 +</code>
 +
 +The ''when:elapsed:'' function takes as its arguments a timeout period (in milliseconds) and a block closure and schedules the closure for execution after the given timeout period. The function returns a subscription object whose single ''cancel'' method can be used to abort the execution of the scheduled code. Once ''cancel'' has been invoked, it is guaranteed that the closure will no longer be executed by the timer module.
 +
 +The milliseconds used to define the timeout period must be provided as a Java ''long'' value. To construct such a value from an AmbientTalk number, the timer module defines the following auxiliary functions:
 +
 +  * ''millisec(ms)'' => convert AmbientTalk number to a Java long value representing a timeout period in milliseconds.
 +  * ''seconds(s)'' => convert AmbientTalk number to a Java long value representing a timeout period in seconds.
 +  * ''minutes(m)'' => convert AmbientTalk number to a Java long value representing a timeout period in minutes.
 +
 +Additionally, the timer module defines a function ''now()'' which returns the current system time as a Java long value.
 +
 +The timer module also defines a function ''whenever:elapsed:'' which repetitively invokes the given block closure every time the timeout period has elapsed. The returned subscription object can be used to eventually stop the repetitive invocation of the closure.
 +
 +The timer module defines a small number of additional utility functions which can be found in the file ''at/support/timer.at''.
  
 ==== Logging Framework ==== ==== Logging Framework ====
 +
 +The module ''/.at.support.logger'' defines a tiny logging framework akin to the well-known [[http://logging.apache.org/log4j|Log4J]] logging framework for Java.
 +
 +Here's a typical example of how to use a logger:
 +<code>
 +import /.at.support.logger;
 +def log := makeLogger("my prefix", INFO); // do not log DEBUG
 +log("a message", ERROR); // message level is optional and defaults to INFO
 +</code>
 +
 +The ''makeLogger'' function returns a function which can be used to log messages to an output object. It takes three arguments, all of which are optional: a string to be prefixed to every logged message (default ''""''), a logging level (default ''DEBUG'') and an output object (default ''system'').
 +
 +The logging level determines which messages are shown on the output log. The available error levels are: ''NONE'', ''DEBUG'', ''WARNING'', ''INFO'', ''ERROR'' and ''FATAL'' in order of exceeding importance. Hence, a log whose default is ''WARNING'' will not show ''DEBUG''-level messages.
 +
 +The output object is an object that understands ''println(string)''. It is used by the logging framework to write its log to the screen, a file, etc.
  
 ==== Object Inspector ==== ==== Object Inspector ====
 +
 +The module ''/.at.support.inspector'' implements a graphical object inspector. The module requires ''java.awt'' and ''javax.swing'' support from the underlying JVM running AmbientTalk. To inspect an object ''o'', execute:
 +
 +<code>
 +import /.at.support.inspector;
 +inspect(o);
 +</code>
 +
 +This will pop up a graphical inspector on the object, listing the object's fields and methods. The object's fields and methods can recursively be inspected through the graphical user interface of the object inspector.
  
 ==== Symbiosis Utilities ==== ==== Symbiosis Utilities ====
 +
 +The module ''/.at.support.symbiosis'' defines a number of utility functions with respect to the symbiosis with the JVM. It defines the following functions which can be used to quickly create a wrapped Java value of the given primitive type:
 +
 +<code>
 +long(anAmbientTalkNumber) -> aJavaLong
 +short(anAmbientTalkNumber) -> aJavaShort
 +float(anAmbientTalkFraction) -> aJavaFloat
 +byte(anAmbientTalkNumber) -> aJavaByte
 +</code>
 +
 +The module also defines the following function:
 +<code>
 +cast: obj into: Interface
 +</code>
 +
 +The ''Interface'' argument should be a Java class wrapper for an interface type. The function returns a Java proxy object implementing the given interface, wrapping the given AmbientTalk object. If this proxy is subsequently passed to Java code, it will hold that ''proxy instanceof Interface''.
  
 ==== Miscellaneous ==== ==== Miscellaneous ====
 +
 +The module ''/.at.support.util'' is a utility module grouping several miscellaneous tasks.
 +
 +=== Random Numbers ===
 +
 +The utility module defines functions for easily generating random numbers. Its implementation uses the random number generators from the underlying JVM. The following functions are the most useful:
 +
 +<code>
 +// generate a random integer in the interval [min, max[
 +def randomNumberBetween(min, max)
 +// generate a random fraction in the interval [min, max[
 +def randomFractionBetween(min, max)
 +</code>
 +
 +=== Custom Object Serialization ===
 +
 +The method ''uponArrivalBecome:'' exported by the utility module creates a transporter object which can be used in ''pass'' meta-level methods to execute code upon deserialization. The closure passed to this function should return the object with which the transported object should be replaced. For example:
 +
 +<code>
 +//inside a mirror
 +def instancevar := ...;
 +def pass() {
 +  uponArrivalBecome: { |instancevar|
 +    // return object to become here
 +  }
 +}
 +</code>
 +
 +The function plays a role similar to ''readResolve'' in the Java object serialization framework.
at/tutorial/appendix.txt · Last modified: 2021/09/24 10:28 by elisag