Differences

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

--- at:tutorial:appendix [2008/07/10 16:43] – added tvcutsem
+++ at:tutorial:appendix [2008/07/10 17:29] – added tvcutsem
@@ 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".
@@ Line 576: / Line 576: @@
 ==== 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 ====
+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 ====
+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 ====
 ==== Miscellaneous ====