Documentation:Aracne atoms

From The BABEL Development Site
Revision as of 16:50, 22 July 2009 by Admin (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Aracne Atoms Documentation for BABEL

System Engineering and Automation Department.

University of Málaga, Spain.




Communications Platform

Services

request-synchronous&blocking

This atom enables to request a service from a module (maybe from itself), in a blocking manner.

AVAILABILITY

Available in:

- Regular Services - Event Handlers - Notification Handlers - Auxiliary Logic

PARAMETERS

  • Service requested -string-: the name of the service being requested, as a sequence of characters, without quoting.
  • Module name -string-: the name of the module that provides the service,as a sequence of characters, without quoting.
  • Service method -id- (not suitable for filling at hand): the name of the method implemented for serving the service, as a C++ identifier.
  • Module variable -id- (not suitable for filling at hand): the name of the variable that holds the module of the server, as a C++ identifier.
  • Service parameters -list-: the list of parameters passed (either variables or values),separated by commas. It has as many members as input plus output parameters of the service being called, and they should be in the same order (firstly the input parameters, then the output ones).
  • Error variable -bool-: the name of a C++ variable already existing for receiving indication of error during the communication of the request: true if error. NOTE: do not confuse this variable with any of the ones that may appear in the "Service parameters -list-" field. The "Error variable -bool-" is not visible in the called service, and its value is filled in automatically by the communication platform (in other words: it will not return any indication set by the called service; if that service needs to return some error indication, it will do that through one of its output parameters, defined in its public interface).
  • Quickest -float-: minimum time in seconds that the service should last in returning a value.
  • Slowest -float-: maximum time in seconds that the service should last in returning a value.
  • Response seconds variable -long- (optional): a C++ variable already existing to hold the seconds part of the timestamp set by the target of the service request when its logic is finished. Notice that this time is valid only if the requester and the requested are running in the same computer.
  • Response microseconds variable -long- (optional): a C++ variable already existing to hold the microseconds part of the timestamp set by the target of the service request when its logic is finished. Notice that this time is valid only if the requester and the requested are running in the same computer.
  • Repetition of module -literal positive number- (optional): a positive number (greater than 0) to distinguish to which repetition of the given target module we are referring with this request (obviously only for the case that the target module of the request is being executed more than once through the repetition feature).


SUPPORTED BY WIZARD

Yes. You can obtain most of the parameters above through several wizards that read them from existing .ice files or from the module itself.

SEE ALSO

request-dynamic&blocking.



request-dynamic&blocking

This atom enables to request a service from a module (maybe from itself), in a blocking manner.

AVAILABILITY

Available in:

- Regular Services - Event Handlers - Notification Handlers - Auxiliary Logic

PARAMETERS

  • Module name -string or variable-: the name of the module that provides the service,as a sequence of characters, with quoting, or as a variable.
  • Service requested -string or variable-: the name of the service being requested, as a sequence of characters, with quoting, or as a variable.
  • Service parameter 1 -variable-: a variable that contains the first parameter of the service.
  • Service parameter 1 inout -character-: a character that can be 'I' or 'O' (without quoting), for indicating if the first parameter is an input or output parameter.

(Analogously for the rest of parameters)

  • Error variable -bool-: the name of a C++ variable already existing for receiving indication of error during the communication of the request: true if no error. NOTE: do not confuse this variable with any of the ones that may appear in the "Service parameters -list-" field. The "Error variable -bool-" is not visible in the called service, and its value is filled in automatically by the communication platform (in other words: it will not return any indication set by the called service; if that service needs to return some error indication, it will do that through one of its output parameters, defined in its public interface).
  • Quickest -float-: minimum time in seconds that the service should last in returning a value.
  • Slowest -float-: maximum time in seconds that the service should last in returning a value.
  • Response seconds variable -long- (optional): a C++ variable already existing to hold the seconds part of the timestamp set by the target of the service request when its logic is finished. Notice that this time is valid only if the requester and the requested are running in the same computer.
  • Response microseconds variable -long- (optional): a C++ variable already existing to hold the microseconds part of the timestamp set by the target of the service request when its logic is finished. Notice that this time is valid only if the requester and the requested are running in the same computer.
  • Repetition of module -literal positive number- (optional): a positive number (greater than 0) to distinguish to which repetition of the given target module we are referring with this request (obviously only for the case that the target module of the request is being executed more than once through the repetition feature).

SUPPORTED BY WIZARD

Yes. You can obtain most of the parameters above through a wizard.

SEE ALSO

request-synchronous&blocking.


terminateservice

This atom makes the current service to end its execution. If the service ouput parameters have not been set, the caller will receive undefined data. The service is terminated even if it is a monitor or monitor+permanent service (or an event or notification handler).

It is useful, for example, when a service shuts down the module. Since the shutdown does not prevent the service from continuing its execution, it should be followed by a terminateservice request.

AVAILABILITY

Available in:

- Regular Services - Event Handlers - Notification Handlers

PARAMETERS

None.

SUPPORTED BY WIZARD

No.

SEE ALSO

shutdown-module

Beta Events

send-beta-event

This atom sends a beta event.

AVAILABILITY

Available in:

- Regular Services. - Event Handlers. - Notification Handlers. - Auxiliary Logic.

PARAMETERS

Event code -identifier-: the identifier of the code of the event to send. Event codes identifiers are defined in modules. From module -identifier- (not suitable for filling at hand): the identifier of the module that defines the event. From Module -free text- (cannot be set in the atom, is automatic): the name of the module that defines the event.

SUPPORTED BY WIZARD

Yes. You can get the data for all the parameters above from .ice files or from the same module.

SEE ALSO

get-event-origin, send-notification.


get-event-origin

This atom gets information about the sender of a beta event.

AVAILABILITY

Available in:

- Event Handlers.

PARAMETERS

Result Variable -char pointer variable-: a C++ variable already existing that will hold the name of the module that has sent the event. Result Maximum Length -unsigned-: a number indicating the maximum length of text that the previous variable can hold. Notice that the variable must have space for that length plus 1 (the ending 0x00 character).

SUPPORTED BY WIZARD

No.

SEE ALSO

send-beta-event, send-notification.

Notifications

send-notification

This atom sends a notification to its own module.

AVAILABILITY

Available in:

- Regular Services. - Event Handlers. - Notification Handlers. - Auxiliary Logic.

PARAMETERS

Notification code -identifier-: the identifier of the code of the notification to send. Notification codes identifiers are defined in their own modules. Module name -identifier- (cannot be set in the atom, is automatic): the identifier of the module.

SUPPORTED BY WIZARD

Yes. You can get the data for all the parameters above from the own module.

SEE ALSO

send-beta-event.



Execution Platform

Concurrency. Critical zones

criticalzonecreate

This atom creates all the critical zones used in the module. Should only be used once in the Startup Logic.

AVAILABILITY

Available in:

- All logics.

PARAMETERS

Quantity -unsigned-: the number of critical zones to create. They will be identified in the module by their index (from 0 to this number minus 1). Result -bool-: the name of a C++ variable already existing for receiving indication of error during the creation: false if error.

SUPPORTED BY WIZARD

No.

SEE ALSO

criticalzonedestroy, criticalzoneenter, criticalzoneleave, numberofcriticalzones.


criticalzonedestroy

This atom destroys all the critical zones used in the module. Should only be used once in the Preending or Postending Logics.

AVAILABILITY

Available in:

- All logics.

PARAMETERS

Result -bool-: the name of a C++ variable already existing for receiving indication of error during the destruction: true if error.

SUPPORTED BY WIZARD

No.

SEE ALSO

criticalzonecreate, criticalzoneenter, criticalzoneleave, numberofcriticalzones.


criticalzoneenter

The logic that uses this atom tries to enter a critical zone. If no other logic is into that zone, it will succeed. Otherwise, the logic is blocked until the zone is free. Only one logic can be into a given zone at the same time.

AVAILABILITY

Available in:

- All logics.

PARAMETERS

Zone index -unsigned-: a number indicating the index of the critical zone into the set of critical zones created for the module. Result -bool-: the name of a C++ variable already existing for receiving indication of error during the entering: false if error.

SUPPORTED BY WIZARD

No.

SEE ALSO

criticalzonecreate, criticalzonedestroy, criticalzoneleave, numberofcriticalzones.


criticalzoneleave

The logic that uses this atom is indicating that it leaves a critical zone. If other logics are waiting to enter, one of them will do it.

AVAILABILITY

Available in:

- All logics.

PARAMETERS

Zone index -unsigned-: a number indicating the index of the critical zone into the set of critical zones created for the module. Result -bool-: the name of a C++ variable already existing for receiving indication of error during the leaving: false if error.

SUPPORTED BY WIZARD

No.

SEE ALSO

criticalzonecreate, criticalzonedestroy, criticalzoneenter, numberofcriticalzones.


numberofcriticalzones

This atom returns the number of critical zones currently existing.

AVAILABILITY

Available in:

- All logics.

PARAMETERS

Result variable -unsigned-: a C++ variable already existing that will hold the number of critical zones: true if error.

SUPPORTED BY WIZARD

No.

SEE ALSO

criticalzonecreate, criticalzonedestroy, criticalzoneenter, criticalzoneleave.

Inter-Process Communications. Local Channels

activate-local-channel

This atom activates one of the local channels for communications with processes in the same computer. A local channel is a bidirectional communication mechanism. Activating one of them opens the stream indicating whether we are the creators of the channel or not. A local channel has a unique string name that permits the other process to refer to it.

AVAILABILITY

Available in:

  • Startup logic.
  • Regular Services.
  • Event Handlers.
  • Notification Handlers.
  • Auxiliary logic.

PARAMETERS

  • Local channel number -0..15-: the number of the channel that is being activated. There exist up to 16 channels available.
  • Local channel name -string-: a double-quoted string or variable holding a string that name the channel (for reference from the other communication point).
  • Creator -bool-: a boolean value that indicates whether a) true: we are the creators of the channel (the first process to open it) or b) false: not (the second one).

SUPPORTED BY WIZARD

No.

SEE ALSO

deactivate-local-channel, send-message-local-channel, receive-message-local-channel.



deactivate-local-channel

This atom deactivates one of the local channels for communications with processes in the same computer.

AVAILABILITY

Available in:

  • All logics.

PARAMETERS

  • Local channel number -0..15-: the number of the channel that is being deactivated. There exist up to 16 channels available.
  • Verbose -bool-: a boolean value that indicates whether we want an automatic output message saying whether the channel has been effectively deactivated.

SUPPORTED BY WIZARD

No.

SEE ALSO

activate-local-channel, send-message-local-channel, receive-message-local-channel.


send-message-local-channel

This atom sends a message through a local channel.

AVAILABILITY

Available in:

  • All logics.

PARAMETERS

  • Local channel number -0..15-: the number of the channel to use. There exist up to 16 channels available.
  • Message data -void *-: the address of the beginning of the message. A message is a sequence of bytes in memory.
  • Message size -unsigned-: the number of bytes of the message.
  • Message type -unsigned-: the type of the message. Messages can be typed for user purposes.
  • Error var. -bool-: a C++ variable already existing to hold if there is any error in the transmission: true if error.

SUPPORTED BY WIZARD

No.

SEE ALSO

activate-local-channel, deactivate-local-channel, receive-message-local-channel.


receive-message-local-channel

This atom receives a message from a local channel.

AVAILABILITY

Available in:

  • All logics.

PARAMETERS

  • Local channel number -0..15-: the number of the channel to use. There exist up to 16 channels available.
  • Sampling -millisecs-: the sampling time. The receiving operation blocks the logic until a message is available in the channel. Meanwhile, is sampling the channel every this value in milliseconds. If this value is 0, only samples once and ends.
  • Timeout -times of sampling-: the maximum number of times a sampling will occur. If it is 0, no limit on the number of samplings will be set.
  • IsTimeOut -bool var-: a C++ variable already existing. If the receiving is timeout, true is returned into this variable.
  • Destination -void *-: the address where to store the received message.
  • Maximum size -unsigned-: the maximum number of bytes to receive. If more bytes are received, the reception will give an error.
  • Size -unsigned-: a C++ variable already existing to hold the actual size in bytes of the received message.
  • Type -unsigned-: the same for holding the type of the message.
  • Error var. -bool-: a C++ variable already existing for holding the result of the operation (false if there is any error).

SUPPORTED BY WIZARD

No.

SEE ALSO

activate-local-channel, deactivate-local-channel, send-message-local-channel.

User Interaction

output-text

This atom outputs a text on the system's standard console, with some information about the module.

AVAILABILITY

Available in:

  • All areas.

PARAMETERS

  • Module name (cannot be set in the atom, is automatic): the name of the module that issues the output.
  • Text -cout sequence-: a cout sequence to output. For example: "message with one variable (" << var << ")". It must not end in "<< endl" or begin with "<<".

SUPPORTED BY WIZARD

No.

SEE ALSO

None.

Real-Time Platform

Timing

rt-suspend

The logic that uses this atom is blocked until a given time passes.

AVAILABILITY

Available in:

  • All logics.

PARAMETERS

  • Seconds -long-: a number indicating the seconds to block. The total time to block is given by the sum of this value and the next parameter.
  • Microseconds -long-: a number of microseconds to add to the previous parameter.

Wait error variable -bool-: the name of a C++ variable that will hold an indication of any error during the blocking: false if error.

SUPPORTED BY WIZARD

No.

SEE ALSO

get-currenttime.



get-timestamp

This atom returns the time when the current logic was requested by its requester (for example, if the logic is a service, it will return the time when the requester of the service issued its request). Notice that this time is not valid if the requester and the requested are running in different computers.

AVAILABILITY

Available in:

  • Regular Services.
  • Event Handlers.
  • Notification Handlers.

PARAMETERS

  • Seconds -long-: a C++ variable already existing that will hold the seconds part of the time.
  • Microseconds -long-: a C++ variable already existing that will hold the microseconds part of the time.

SUPPORTED BY WIZARD

No.

SEE ALSO

get-currenttime.


get-currenttime

This atom returns the current time.

AVAILABILITY

Available in:

  • All logics.

PARAMETERS

  • Seconds -long-: a C++ variable already existing that will hold the seconds part of the time.
  • Microseconds -long-: a C++ variable already existing that will hold the microseconds part of the time.

SUPPORTED BY WIZARD

No.

SEE ALSO

difftimes.


difftimes

This atom returns the difference between two given times (variable=time1-time2).

AVAILABILITY

Available in:

  • All logics.

PARAMETERS

  • Seconds1 -long-: the seconds part of the second time measurement.
  • Microseconds1 -long-: the microseconds part of the second time measurement.
  • Seconds2 -long-: the seconds part of the first time measurement.
  • Microseconds2 -long-: the microseconds part of the first time measurement.
  • Seconds variable -long-: a C++ variable already existing that will hold the seconds part of the time given by (second time - first time).
  • Microseconds variable -long-: a C++ variable already existing that will hold the microseconds part of the time given by (second time - first time).

SUPPORTED BY WIZARD

No.

SEE ALSO

get-currenttime.

Fault-Tolerance Platform

Error Discovering

user-log

This atom issues a log to the time-logs of the module, for future off-line consulting through the BABEL Debugger. The text given in the atom will be automatically accompanied by a timestamp.

AVAILABILITY

Available in:

  • All logics.

PARAMETERS

  • Log text -char *-: a double-quoted string (or variable that holds a char *) with the text of the log.

SUPPORTED BY WIZARD

No.

SEE ALSO

None.

Hardware Platform

None defined yet.

Miscellaneous

check-disconnection

This atom checks if the module is currently being shut down. It is not necessary to protect all the body of the monitor+permanent services with this check, since they are already protected in that way (they finish their execution automatically if at their beginning they find the module is shutting down).

AVAILABILITY

Available in:

  • All areas.

PARAMETERS

  • Check variable -bool-: a C++ variable already existing for holding the result of the checking: true if module currently shutting down.

SUPPORTED BY WIZARD

No.

SEE ALSO

shutdown-module.


return-server-routine

This atom returns from the logic being executed.

AVAILABILITY

Available in:

  • Regular Services.
  • Event Handlers.
  • Notification Handlers.

PARAMETERS

<None>.

SUPPORTED BY WIZARD

No.

SEE ALSO

shutdown-module.



shutdown-module

This atom shuts down the module. However, the module is not immediately shut down since other services and threads must be terminated in a graceful fashion. If the shutdown atom returns "true", the logic where the shutdown is done should terminate with a "terminateservice" atom.

AVAILABILITY

Available in:

  • Regular Services.
  • Event Handlers.
  • Notification Handlers.
  • Auxiliary Logic

PARAMETERS

  • Result variable -bool-: a C++ variable already existing to hold the result of shutting down: true if no error (otherwise, no shutdown is done).

SUPPORTED BY WIZARD

No.

SEE ALSO

check-disconnection, terminateservice


disable-menu

This atom disables the main menu shown by the module for basic control of its operation, leaving available the keyboard input from the user.

AVAILABILITY

Available in:

  • All areas.

PARAMETERS

  • Result variable -bool-: a C++ variable already existing to hold the result of disabling the menu: true if no error.

SUPPORTED BY WIZARD

No.

SEE ALSO

enable-menu.



enable-menu

This atom enables the main menu shown by the module for basic control of its operation, avoiding to use (by the logics of the module) the keyboard input from the user.

AVAILABILITY

Available in:

  • All areas.

PARAMETERS

Result variable -bool-: a C++ variable already existing to hold the result of disabling the menu: true if no error.

SUPPORTED BY WIZARD

No.

SEE ALSO

disable-menu.


read-commandlineargument

This atom reads a command line argument passed to the executable file of the module. Arguments are assumed to have two parts separated by a space. The first part is the name of the argument and begins with "-". The second part is the value of the argument. For example: module_executable -ArgumentName <value>

AVAILABILITY

Available in:

  • Startup logic.

PARAMETERS

  • Argument name -double-quoted string-: a double-quoted string (or variable that holds a char *) with the name of the argument.
  • Argument value variable -char *-: a C++ variable already existing that will be set to the address of the argument value, if any. That value must not be changed.
  • Exists variable -bool-: a C++ variable already existing that will hold the existence of the given argument: true if the argument was found.

SUPPORTED BY WIZARD

No.

SEE ALSO

None.

Retrieved from "https://babel.isa.uma.es/babel2/index.php?title=Documentation:Aracne_atoms&oldid=559"