desmoj.extensions.crossbar

Class MessageCrossbar<T extends SimProcess>

java.lang.Object

desmoj.core.simulator.NamedObject

desmoj.core.simulator.ModelComponent

desmoj.core.simulator.Reportable

desmoj.extensions.crossbar.MessageCrossbar<T>

public class MessageCrossbar<T extends SimProcess>
extends Reportable

The MessageCrossbar is a higher modeling construct used to synchronize processes.

The MessageCrossbare permits the creation of any number of MessageChannels on it. Over these channels messages can be sent from one sender process to any number of receiver processes. To receive a message a process has to wait for it on a message channel. Once a process starts waiting on a channel it is automatically passivated and blocked. If a process sends a message to a channel all process waiting there will be reactivated and unregistered from the message channel and the MessageCrossbar.

It is possible for a process to wait on several message channels simultaneously. It will be activated and removed from all channels if a message is received on any of those channels. In parallel it is also possible for a process to send messages to several channels simultaneously.

Version:

DESMO-J, Ver. 2.5.1c copyright (c) 2015

Author:

Malte Unkrig Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See Also:

MessageChannel, CrossbarMessage

Constructor Summary

Constructors

Constructor and Description
MessageCrossbar(Model owner, java.lang.String name, boolean showInReport, boolean showInTrace) Creates a MessageCrossbar object with all parameters required.

Method Summary

Modifier and Type	Method and Description
Reporter	createDefaultReporter() This method provides a reporter to generate report data about this reportable.
MessageChannel<T>	createMessageChannel(java.lang.String channelName) Creates a new MessageChannel with is automatically associated with the MessageCrossbar.
<ST extends T> MessageChannel<ST>	createMessageChannel(java.lang.String channelName, java.lang.Class<ST> desiredGenericType, boolean showInReport, boolean showInTrace) Creates a new MessageChannel with is automatically associated with the MessageCrossbar.
long	getDeliveredMessages()
long	getInterruptedWaits()
long	getLostMessages()
MessageChannel<T>	getMessageChannel(java.lang.String channelName) Returns the MessageChannel identified by the given name.
long	getObservations() Returns the number of observations made by the reportable object.
long	getProcessActivations()
long	getReceivedMessages()
void	reset() Resets the counter for observations made by this reportable.
TimeInstant	resetAt() Shows the point in simulation time when the last reset of this reportable was made.
void	sendMessage(CrossbarMessage message, java.util.List<MessageChannel<T>> channelsToSendTo) Sends the given CrossbarMessage to the specified message channels, thereby activating all processes that are waiting on these channel.
CrossbarMessage	waitForMessage(java.util.List<MessageChannel<T>> channelsToWaitOn) Wait for a CrossbarMessage on the specified message channels, thereby passivating the current process.
CrossbarMessage	waitForMessage(java.util.List<MessageChannel<T>> channelsToWaitOn, TimeInstant waitUntil) Wait for a CrossbarMessage on the specified message channels, thereby passivating the current process.
CrossbarMessage	waitForMessage(java.util.List<MessageChannel<T>> channelsToWaitOn, TimeSpan maxWaitTime) Wait for a CrossbarMessage on the specified message channels, thereby passivating the current process.

Methods inherited from class desmoj.core.simulator.Reportable

getCorrespondingSchedulable, getDescription, getReporter, incrementObservations, incrementObservations, reportIsOn, reportOff, reportOn, setCorrespondingSchedulable, setDescription, setReporter

Methods inherited from class desmoj.core.simulator.ModelComponent

current, currentEntity, currentEntityAll, currentEvent, currentModel, currentSimProcess, debugIsOn, debugOff, debugOn, getModel, isExperimentCompatible, isModelCompatible, presentTime, sendDebugNote, sendMessage, sendTraceNote, sendWarning, skipTraceNote, skipTraceNote, traceIsOn, traceOff, traceOn

Methods inherited from class desmoj.core.simulator.NamedObject

getName, getQuotedName, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MessageCrossbar

public MessageCrossbar(Model owner,
                       java.lang.String name,
                       boolean showInReport,
                       boolean showInTrace)

Creates a MessageCrossbar object with all parameters required. The MessageCrossbar registers itself at the given model

Parameters:

name - java.lang.String : The name of this reportable

owner - Model : The model this reportable is associated to

showInReport - boolean : Flag for showing the report Set it to true if reportable should show up in report. Set it to false if reportable should not be shown in report.

showInTrace - boolean : Flag for showing this reportable in trace files. Set it to true if reportable should show up in trace. Set it to false if reportable should not be shown in trace.

Method Detail

createMessageChannel

public MessageChannel<T> createMessageChannel(java.lang.String channelName)

Creates a new MessageChannel with is automatically associated with the MessageCrossbar. If a channel with the specified name already exists it will be returned instead of a new channel.

Parameters:

channelName - String : The name of the new channel

Returns:

The new MessageChannel instance

createMessageChannel

public <ST extends T> MessageChannel<ST> createMessageChannel(java.lang.String channelName,
                                                              java.lang.Class<ST> desiredGenericType,
                                                              boolean showInReport,
                                                              boolean showInTrace)

Creates a new MessageChannel with is automatically associated with the MessageCrossbar. If a channel with the specified name already exists it will be returned instead of a new channel.

By specifying the generic type of the MessageChannel this method allows the creation of MessageChannels which are more specifically typed than the MessageCrossbar. In this way on a generally typed MessageCrossbar< SimProcess> a MessageChannel< Truck> (where Truck extends SimProcess) can be created.

Parameters:

channelName - String : The name of the new channel

desiredGenericType - Class : The generic typ of the channel.

showInReport - boolean : Flag for showing the report Set it to true if reportable should show up in report. Set it to false if reportable should not be shown in report.

showInTrace - boolean : Flag for showing this reportable in trace files. Set it to true if reportable should show up in trace. Set it to false if reportable should not be shown in trace.

Returns:

The new MessageChannel instance

createDefaultReporter

public Reporter createDefaultReporter()

This method provides a reporter to generate report data about this reportable. In this general implementation, a StandardReporter is returned. Lacking further knowledge about a specific reportable, the StandardReporter is only able to read out the reportable's name, number of observations and time of last reset.
Thus, it is highly recommended that subclasses override this method to return an appropriate default reporter for the specific reportable object. All reportable objects in DESMO-J like Accumulate, Tally, Count, Queue, and many others provide such reporters.
If you want to extend the framework with new reportable objects, provide a suitable reporter as well and override this method to return an instance of the reporter.
If you just need to replace the reporter used by an existing reportable (while not requiring any changes to the reportable itself), there is no need to create a subclass of the reportable: Instead of overriding this method, just call setReporter() to have this reportable use a custom reporter instead of the default reporter.

Returns:

desmoj.core.report.Reporter : A specific reporter for this reportable

getDeliveredMessages

public long getDeliveredMessages()

Returns:

The number of delivered messages. A message is considered delivered if it was forwarded to at least one waiting process.

getInterruptedWaits

public long getInterruptedWaits()

Returns:

The number of process which were interrupted while waiting on the MessageCrossbar because their max wait time was exceeded.

getLostMessages

public long getLostMessages()

Returns:

The number of message which were sent to this MessageCrossbar but couldn't be forwarded to a receiver because no process was waiting on the MessageCrossbar at the time the message was received.

getMessageChannel

public MessageChannel<T> getMessageChannel(java.lang.String channelName)

Returns the MessageChannel identified by the given name.

Parameters:

channelName - The name of the channel

Returns:

The MessageChannel identified by the given name, or null if no channel with that name is managed by the MessageCrossbar.

getObservations

public long getObservations()

Description copied from class: Reportable

Returns the number of observations made by the reportable object.

Overrides:

getObservations in class Reportable

Returns:

The number of processes which have been handled by this message MessageCrossbar (meaning processes which entered the channel and also left it again).

getProcessActivations

public long getProcessActivations()

Returns:

The number of process that were successfully activated by a delivered message.

getReceivedMessages

public long getReceivedMessages()

Returns:

The number of messages which were sent to this channel.

reset

public void reset()

Resets the counter for observations made by this reportable. The point of simulation time this method was called will be stored and can be retrieved using method resetAt().

Overrides:

reset in class Reportable

resetAt

public TimeInstant resetAt()

Shows the point in simulation time when the last reset of this reportable was made.

Overrides:

resetAt in class Reportable

Returns:

TimeInstant : The point of simulation time of the last reset.

sendMessage

public void sendMessage(CrossbarMessage message,
                        java.util.List<MessageChannel<T>> channelsToSendTo)

Sends the given CrossbarMessage to the specified message channels, thereby activating all processes that are waiting on these channel.

Parameters:

message - The message to send to the specified channels

channelsToSendTo - The channels to which the message will be sent

waitForMessage

public CrossbarMessage waitForMessage(java.util.List<MessageChannel<T>> channelsToWaitOn)
                               throws SuspendExecution

Wait for a CrossbarMessage on the specified message channels, thereby passivating the current process. The process is not reactivated until a message is received.

Parameters:

channelsToWaitOn - The channels on which to wait for a message

Returns:

The CorssbarMessage received after waiting

Throws:

SuspendExecution

waitForMessage

public CrossbarMessage waitForMessage(java.util.List<MessageChannel<T>> channelsToWaitOn,
                                      TimeInstant waitUntil)
                               throws InterruptException,
                                      SuspendExecution

Wait for a CrossbarMessage on the specified message channels, thereby passivating the current process. The process is not reactivated until a message is received. The parameter waitUntil specifies the point in time to which the current process will wait for a message. If no message is received before that time, the process will be interrupted and a DelayedInterruptException will be thrown.

Parameters:

channelsToWaitOn - The channels on which to wait for a message

waitUntil - The point in time at which the waiting will be interrupted

Returns:

The CorssbarMessage received after waiting

Throws:

InterruptException

SuspendExecution

waitForMessage

public CrossbarMessage waitForMessage(java.util.List<MessageChannel<T>> channelsToWaitOn,
                                      TimeSpan maxWaitTime)
                               throws InterruptException,
                                      SuspendExecution

Wait for a CrossbarMessage on the specified message channels, thereby passivating the current process. The process is not reactivated until a message is received. The parameter maxWaitTime specifies maximum time the current process will wait for a message. If no message is received before this amount of time has elapsed, the process will be interrupted and a DelayedInterruptException will be thrown.

Parameters:

channelsToWaitOn - The channels on which to wait for a message

maxWaitTime - The maximum amount of time until the waiting will be interrupted

Returns:

The received message

Throws:

SuspendExecution

InterruptException