at:tutorial:appendix
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
at:tutorial:appendix [2008/07/10 16:02] – added tvcutsem | at:tutorial:appendix [2020/04/28 19:47] – summary elisag | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Appendix ====== | + | ====== Appendix: Libraries |
- | In the appendix, we explain useful libraries available to the AmbientTalk/ | + | In the appendix, we explain useful libraries available to the AmbientTalk/ |
+ | |||
+ | The Ambientalk standard library ('' | ||
===== Unit Testing Framework ===== | ===== Unit Testing Framework ===== | ||
Line 27: | Line 29: | ||
This will execute all '' | This will execute all '' | ||
- | Like in JUnit and SUnit, it is possible to define two methods named '' | + | Like in JUnit and SUnit, it is possible to define two methods named '' |
==== Assertions ==== | ==== Assertions ==== | ||
Line 82: | Line 84: | ||
It is also possible to use '' | It is also possible to use '' | ||
+ | |||
+ | <note tip> | ||
+ | See the [[distribution# | ||
+ | </ | ||
==== Test Suites ==== | ==== Test Suites ==== | ||
Line 388: | Line 394: | ||
The files in the '' | The files in the '' | ||
- | ==== Futures and Multifutures ==== | ||
- | === Futures === | ||
- | The module ''/ | + | |
+ | ==== Futures ==== | ||
+ | |||
+ | The module ''/ | ||
The module exports the type tags '' | The module exports the type tags '' | ||
Line 413: | Line 420: | ||
</ | </ | ||
- | Finally, the futures module also provides some auxiliary functions, of which '' | + | The '' |
+ | |||
+ | === Auxilary functions in the futures module ==== | ||
+ | |||
+ | The futures module also provides some auxiliary functions, of which '' | ||
< | < | ||
- | when: (group: [ a<-m(), b<-n() ]) becomes: { |values| | + | when: (group: [ a<-m()@FutureMessage, b<-n()@FutureMessage |
def [aResult, bResult] := values; | def [aResult, bResult] := values; | ||
... | ... | ||
Line 422: | Line 433: | ||
</ | </ | ||
- | === Multifutures === | + | Another useful auxilary function is '' |
- | The module ''/ | + | < |
+ | future: { |return| | ||
+ | // some computation | ||
+ | return(val) | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | This is actually equivalent to the slightly more verbose code: | ||
+ | |||
+ | < | ||
+ | def [fut,res] := makeFuture(); | ||
+ | try: { // some computation | ||
+ | res.resolve(val); | ||
+ | } catch: Exception using: { |e| res.ruin(e) } | ||
+ | fut; | ||
+ | </ | ||
+ | |||
+ | ==== Multifutures ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | A multifuture is constructed as follows: | ||
+ | < | ||
+ | def [mf, resolver] := makeMultiFuture(n, | ||
+ | </ | ||
+ | |||
+ | The parameter '' | ||
+ | |||
+ | A multifuture accepts the following listeners: | ||
< | < | ||
Line 430: | Line 469: | ||
</ | </ | ||
- | This listener is invoked whenever the future is resolved with a new value. Its code can thus be executed multiple times. | + | The above listener is invoked whenever the future is resolved with a new value. Its code can thus be executed multiple times. |
< | < | ||
Line 438: | Line 477: | ||
</ | </ | ||
- | 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. | + | The above listener |
Note the following properties of multifutures: | Note the following properties of multifutures: | ||
Line 453: | Line 492: | ||
When the message sent to a multireference is annotated with @Due(t), the timeout is applied to the implicit multifuture, | When the message sent to a multireference is annotated with @Due(t), the timeout is applied to the implicit multifuture, | ||
+ | |||
+ | |||
+ | ==== Leased Object References ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | < | ||
+ | The implementation of leased object references actually consists of two files: ''/ | ||
+ | </ | ||
+ | |||
+ | The '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | 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 trigger expiration of a single-call leased reference. | ||
+ | |||
+ | The '' | ||
+ | |||
+ | < | ||
+ | renew: leasedRef for: interval; // renews a lease | ||
+ | revoke: leasedRef; // revokes a lease | ||
+ | leaseTimeLeft: | ||
+ | when: lease expired: {...}; // trigger a closure when the lease expires | ||
+ | </ | ||
+ | |||
+ | The '' | ||
+ | |||
+ | Finally, the '' | ||
+ | |||
+ | |||
+ | |||
+ | ==== TOTAM ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | Please have a look to [[: | ||
==== Dynamic Variables ==== | ==== Dynamic Variables ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | A dynamic variable can be defined as follows: | ||
+ | < | ||
+ | def name := dynamicVariable: | ||
+ | </ | ||
+ | |||
+ | It can be read as follows: | ||
+ | < | ||
+ | ?name or name.value | ||
+ | </ | ||
+ | |||
+ | It can be assigned only within a limited dynamic scope, as follows: | ||
+ | < | ||
+ | with: name is: newval do: { code } | ||
+ | // or | ||
+ | name.is: newval in: { code } | ||
+ | </ | ||
+ | |||
+ | When '' | ||
+ | |||
+ | By convention, we prefix the names of dynamic variables with a '' | ||
+ | |||
+ | You can find more usage examples of dynamic variables in the unit test included in the file '' | ||
==== Ambient References ==== | ==== Ambient References ==== | ||
+ | |||
+ | Ambient references are defined in the module ''/ | ||
+ | |||
+ | < | ||
+ | import / | ||
+ | deftype Printer; | ||
+ | def printers := ambient: Printer; | ||
+ | </ | ||
+ | |||
+ | In the above code, '' | ||
+ | |||
+ | Ambient references ship with two so-called " | ||
==== Structural Types ==== | ==== Structural Types ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | A structural type can be branded with type tags. In this case, objects only conform to the type if they are structurally conformant **and** if they are tagged with the structural type's brands. | ||
+ | |||
+ | Use the '' | ||
+ | |||
+ | < | ||
+ | def PersonProtocol := protocol: { | ||
+ | def name; | ||
+ | def age; | ||
+ | } named: `Person; | ||
+ | </ | ||
+ | |||
+ | The '' | ||
+ | |||
+ | < | ||
+ | def tom := object: { | ||
+ | def name := " | ||
+ | def age() { 24 }; | ||
+ | } implements: PersonProtocol; | ||
+ | </ | ||
+ | |||
+ | You can also create a protocol from an object: | ||
+ | < | ||
+ | |||
+ | You can test protocol conformance in either of two styles: | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | You can also force a '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | More usage examples of structural types can be found in the unit test defined in the file '' | ||
==== Traits ==== | ==== Traits ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | Using the '' | ||
+ | |||
+ | To define a " | ||
+ | < | ||
+ | trait: { | ||
+ | ... | ||
+ | } requiring: Protocol; | ||
+ | </ | ||
+ | |||
+ | The above code creates a trait that can only be composed into an object adhering to the specified protocol. To compose traits, use the following language construct: | ||
+ | |||
+ | < | ||
+ | object: { | ||
+ | use: { | ||
+ | import T1 exclude ...; | ||
+ | import T2 alias ...; | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | The '' | ||
+ | |||
+ | Note that the place where '' | ||
+ | |||
+ | Usage examples can be found in the unit tests in the file '' | ||
+ | |||
+ | ===== Utilities ===== | ||
+ | |||
+ | The files in the '' | ||
+ | |||
+ | |||
+ | ==== Timing Utilities ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | < | ||
+ | def subscription := when: timeoutPeriod elapsed: { | ||
+ | ... | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | The '' | ||
+ | |||
+ | The milliseconds used to define the timeout period must be provided as a Java '' | ||
+ | |||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | Additionally, | ||
+ | |||
+ | The timer module also defines a function '' | ||
+ | |||
+ | Finally, there is a variant of '' | ||
+ | |||
+ | < | ||
+ | def testAsyncNearbyPlayerReply(){ | ||
+ | def nearbyPlayers := // search 2 nearby player orjbects; | ||
+ | // wait a bit so that there are the 2 members. | ||
+ | when: 2.seconds elapsedWithFuture: | ||
+ | self.assertEquals(2, | ||
+ | } | ||
+ | }; | ||
+ | </ | ||
+ | |||
+ | |||
+ | ==== Logging Framework ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | Here's a typical example of how to use a logger: | ||
+ | < | ||
+ | import / | ||
+ | def log := makeLogger(" | ||
+ | log("a message", | ||
+ | </ | ||
+ | |||
+ | The '' | ||
+ | |||
+ | The logging level determines which messages are shown on the output log. The available error levels are: '' | ||
+ | |||
+ | The output object is an object that understands '' | ||
+ | |||
+ | ==== Object Inspector ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | < | ||
+ | import / | ||
+ | inspect(o); | ||
+ | </ | ||
+ | |||
+ | This will pop up a graphical inspector on the object, listing the object' | ||
+ | |||
+ | ==== Symbiosis Utilities ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | < | ||
+ | long(anAmbientTalkNumber) -> aJavaLong | ||
+ | short(anAmbientTalkNumber) -> aJavaShort | ||
+ | float(anAmbientTalkFraction) -> aJavaFloat | ||
+ | byte(anAmbientTalkNumber) -> aJavaByte | ||
+ | </ | ||
+ | |||
+ | The module also defines the following function: | ||
+ | < | ||
+ | cast: obj into: Interface | ||
+ | </ | ||
+ | |||
+ | The '' | ||
+ | |||
+ | ==== Miscellaneous ==== | ||
+ | |||
+ | The module ''/ | ||
+ | |||
+ | === 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: | ||
+ | |||
+ | < | ||
+ | // generate a random integer in the interval [min, max[ | ||
+ | def randomNumberBetween(min, | ||
+ | // generate a random fraction in the interval [min, max[ | ||
+ | def randomFractionBetween(min, | ||
+ | </ | ||
+ | |||
+ | === Custom Object Serialization === | ||
+ | |||
+ | The method '' | ||
+ | |||
+ | < | ||
+ | //inside a mirror | ||
+ | def instancevar := ...; | ||
+ | def pass() { | ||
+ | uponArrivalBecome: | ||
+ | // return object to become here | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | The function plays a role similar to '' |
at/tutorial/appendix.txt · Last modified: 2021/09/24 10:28 by elisag