Documentation:Aracne atoms

From The BABEL Development Site
Revision as of 12:12, 22 May 2009 by Jlblanco (talk | contribs) (Inter-Process Communications)

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.
  • Error variable -bool-: the name of a C++ variable already existing for receiving indication of error during the request: true if error.
  • 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 request: true if no error.
  • 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: true 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: true 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: true 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

User Interaction

Real-Time Platform

Timing

Fault-Tolerance Platform

Error Discovering

Hardware Platform

Miscellaneous