Timeout triggered event is used when you need to perform an action at some particular moment of time (or on some particular date). Such an event occurs exactly in Timeout time after it is started.
Timeout triggered event has several work modes, allowing the user to efficiently solve various tasks, e.g.:
If you expect several events,
performing similar actions, to be scheduled at the same time, use dynamic events instead
of events.
User
control – the event will work in manual mode. It will
occur if and only if user calls the event’s restart()
function passing the timeout as the argument, for instance myEvent.restart(15).
If the timeout is fixed and known
beforehand, you can define it once in the Timeout property and
simply call myEvent.restart()
without specifying the timeout as a function parameter.
Occurs
once – the event will occur only once exactly in the
specified Occurrence
time (absolute) or Occurrence
date. You can define the occurrence time as a calendar
date (choose Use
calendar dates) or as a number of model time units to be
passed from the model start (choose Use
model time).
Please note that here you define
the absolute
time and in the case the event will be created after the specified
time, it will never occur.
Cyclic
– the event will occur cyclically. Using the controls below, you define
the First occurrence time
(absolute)
or Occurrence date
and the Recurrence time
for an event. The first occurrence time can be defined either as a
calendar date (choose Use
calendar dates), or as a number of model time units to be
passed from the model start (choose Use
model time).
Please note that you define absolute
times. If event will be created after the specified first occurrence
time, the model will schedule the first occurrence time in the past and
then will successively increment it with Recurrence time.
The first time that will exceed the current model time will be used as
the actual first occurrence time. The next occurrence times will be
counted as it should be by adding the defined Recurrence time.
If you want to use relative
times (i.e. count the first occurrence time from the moment this event
will be created), use the time()
function in the First
occurrence time
(absolute) property. time()
will refer to the moment this event was created at.
Name – The name of the event. The name is used to identify and access the event.
Show name – If selected, the name of the event is displayed on a presentation diagram.
Ignore – If selected, the event is excluded from the model.
Visible - If selected, the event is visible on a presentation at runtime.
Trigger
type – The event's trigger type:
Timeout – The event is timeout triggered. The event occurs according to the chosen Mode.
Rate – The event is rate triggered. The event occurs with the specified Rate.
Condition – The event is condition triggered. The event occurs when the specified boolean Condition becomes true.
Mode – [Visible if Trigger type is Timeout] Choose here the mode of the timeout triggered event:
User
control
– The event will work in manual mode. It will occur only when the user
calls the event’s restart function passing the timeout as the argument,
for instance myEvent.restart(15).
If the timeout is fixed, you can
define it once in the Timeout
property and simply call myEvent.restart()
without specifying the timeout as a function parameter.
Occurs once
– The event will occur only once exactly in the specified (absolute) or Occurrence date. You
can define the occurrence time as a calendar date (choose Use calendar dates)
or as a number of model time units to be passed from the model start
(choose Use model time).
Please note that here you define
the absolute time
and in the case the event will be created after the specified time, it
will never occur.
Cyclic
– The event will occur cyclically. You define the First occurrence time (absolute)
or Occurrence date
and the Recurrence time
for an event. The first occurrence time can be defined either as a
calendar date (choose Use
calendar dates), or as a number of model time units to be
passed from the model start (choose Use
model time).
Please note that you define absolute times. If
you want to use relative
times (i.e. count the first occurrence time from the moment this event
will be created), use time()
function in the First
occurrence time
(absolute) property. time()
will refer to the moment this event was created at..
Timeout – [Visible if Trigger type is Timeout and Mode is User control] The expression evaluating the timeout that should pass from the moment when the user starts the event by calling its restart() function.
Use model time - [Visible if Trigger type is Timeout and Mode is Occurs once or Cyclic] If selected, the event will occur at the specified model time.
Use calendar dates - [Visible if Trigger type is Timeout and Mode is Occurs once or Cyclic] If selected, the event will occur at the specified calendar date.
Occurrence time (absolute) – [Visible if Trigger type is Timeout, Mode is Occurs once and Use model time is selected] The absolute time of event occurrence defined as a number of model time units to be passed from the model start.
Occurrence date - [Visible if Trigger type is Timeout, Mode is Occurs once or Cyclic and Use calendar dates is selected] The calendar date and time of the event.
First occurrence time (absolute) – [Visible if Trigger type is Timeout, Mode is Cyclic and Use model time is selected] The absolute time of the first occurrence of the cyclic event, defined as a number of model time units to be passed from the model start.
Recurrence time – [Visible if Trigger type is Timeout and Mode is Cyclic] The recurrence time of the cyclic event.
Rate – [Visible if Trigger type is Rate] The rate triggering the event. Event will occur with the timeout distributed exponentially with the parameter rate. I.e. if the rate is 5, event will occur on average 5 times per time unit.
Condition – [Visible if Trigger type is Condition] The condition triggering the event. Event will occur when the specified Boolean expression is true.
Log to database – If selected, information on all event occurrences will be logged into the model execution log events_log.
Java code to be executed on event occurrence.
You can control the timeout triggered event programmatically via its API
boolean isActive() - Returns true, if the event is currently scheduled, false otherwise.
void reset() - Cancels the currently scheduled event, if any. In case the event is Cyclic, the cycle would not resume until restart() or restart(double t) is called.
void restart() - Cancels the currently scheduled event, if any, and schedules the next occurrence according to the Timeout specified.
void
restart(double timeout) - Cancels the currently scheduled
event, if any, and schedules the next occurrence in time timeout. Timeout is specified in model time units.
If the event is Cyclic,
it will then continue occurring at the original timeout/rate.
Parameter: timeout - time (from the
function call moment), in which the event will be scheduled.
void
restart(double timeout, TimeUnits units) - Cancels the
currently scheduled event, if any, and schedules the next occurrence in
time timeout. Timeout
is specified in given
time units.
If the event is Cyclic,
it will then continue occurring at the original timeout/rate.
Parameters:
timeout - time (from
the function call moment), in which the event will be scheduled.
units - time unit
constant
Example: event.restart(10, MINUTE)
schedules event
occurrence in 10 minutes from the current moment of model time.
void
restartTo(double time) - Cancels the currently scheduled
event, if any, and schedules the next occurrence at the absolute model
time time. Timeout is
specified in model time
units. If the event is Cyclic,
it will then continue occurring at the original timeout/rate.
This method looks similar to the restart(time
- time()) call but it is actually different because it
eliminates numeric calculation error which may occur on any machine.
Parameter: time - model time (absolute),
at which the event will be scheduled.
void
restartTo(double time,
TimeUnits units)
- Cancels the currently scheduled event, if any, and schedules the next
occurrence at the absolute model time time.
Timeout is specified in
given time units. If the event is Cyclic, it will then
continue occurring at the original timeout/rate.
This method seems to be like the call restart(time
- time()) but it is different because it eliminates
numeric calculation error which may occur on any machine.
Parameters:
time - model time
(absolute), at which the event will be scheduled.
units - time unit
constant
void
restartTo(Date date)
- Cancels the currently scheduled event, if any, and schedules the next
occurrence at the model date date.
If the event is Cyclic,
it will then continue occurring at the original timeout/rate.
This method seems to be like the call restart(toTimeoutInCalendar(...))
but it is different because it eliminates numeric calculation error
which may occur on any machine.
Parameter: date - model date, at which
the event will be scheduled.
void
suspend() - Cancels the currently scheduled event, if any,
and remembers the remaining time so that it can be resumed by calling resume(). If the event is not
scheduled at the time of calling suspend(),
the subsequent resume will result in nothing.
Note that you should not call this function (i.e. should not try to
suspend the event) from its own action code: it will have the effect of
reset().
void resume() - Re-schedules the previously suspended event in the remaining time. Does nothing if event was never suspended or was reset or restarted after it was last suspended.
double
getRest() - Returns the time remaining before the
scheduled occurrence of the event, in
model time units.
If the event is not scheduled, the function returns infinity
.
double
getRest(TimeUnits units) - Returns the time remaining
before the scheduled occurrence of the event, in given time units.
If the event is not scheduled, the function returns infinity
.
Parameter: units - time unit
constant
Example: event.getRest(MINUTE) will
return the remaining time in minutes.