Dispatcher
Dispatcher: Dispatch Point for Items
The Dispatcher is a "waiting station" for Items, and can have multiple outgoing paths.
It is used in situations where an Item may be called upon by other objects, or in model logic in no particular order eg. a repairman servicing a group of machines, or a part which may be required by a range of assembly stations.
Like a Queue, a Dispatcher has a maximum capacity, screen length and orientation.
A Dispatcher can be classified as “Logical with Capacity”, as they can hold items, and no time passes when they process items.
Any class of Item can wait in a Dispatcher, and can leave it at any time - unlike a First In First Out Queue.
Items entering a Dispatcher will wait there until they are allowed to proceed further
(ie. one of their outgoing paths will accept them).
Unless it is blocked, a regular Item will immediately moves out from a Dispatcher if any of its paths lead either directly - or through a Switch - to a Multi-server, Queue, Splitter, Exit or another Dispatcher.
A Carrier Item may need to wait in a Dispatcher that has a path to a PickUp Object, until the PickUp Object has collected enough Items and requests the Carrier Item to enter it and take away some or all of the items it holds.
Dispatcher States
The Dispatcher appears in outline like a queue but has a double line below. Items accumulate in Dispatchers as they wait for tasks.
The icon for the Dispatcher Mode does not change to represent these different states.
Idle No Items are at the Dispatcher.
Wait At least 1 Item is at the Dispatcher.
Use with PickUp Objects
When operating with Carrier Items, Dispatchers can respond to PickUp Objects, holding the Carrier Item until requested, then releasing it to perform a PickUp of Items from that object.
In such cases the outgoing path will often return the Carrier Item (once its task is complete) to the Dispatcher so the Carrier Item can wait for the next request.
In this way a Carrier Item can act as a transportation resource operating in a cyclic manner.
Use with Switch
Departures from a Dispatcher may be controlled by a Switch which is configured to release an item (or items), and direct the item along a particular path, when specific conditions are met.
This Switch needs to be able to block items if it is to operate as a filter, holding some items back and latting others through.
Dispatcher Modes
Dispatchers have a range of different modes, which make them a powerful object in your modelling. Some modes display an icon in their corner to clarify their use:
Normal
Default Mode.
Used in situations where an Item may be called upon in no particular order by PickUp objects, or in model logic in combination with Switch Objects.
Send Message
This Mode is used when you want to send an Item to another location in your model to be processed.
In this Mode you nominate a Target Entry from a list of available Message Entries.
The Message Entry nominated need not be in the same subsystem.
The Target option becomes available in the Object’s Menu when this Mode is selected.
When an item enters this dispatcher, a "message" is sent to the nominated Entry, which then produces a "Message Item".
This Message Item is identical to the original item except for its item ID.
It contains all of the attributes and values of the original item in the dispatcher.
The “original item” is held by the Dispatcher until the "Message Item" is sent to an Exit object, whereupon the original item is then free to leave the Dispatcher.
When the Message Item passes through the Exit, it passes back to the original item its characteristics, including Attributes, Trip details, Icon, and Class.
Many Dispatchers can call upon a single Message Entry.
This enables you to centrally/remotely manage changes to any or all of an an item's Attributes; Icon; Route details; and even Class.
Treatment of Carried Items
When Carrier Items are sent as Message Items they carry their Items with them, and unless otherwise unloaded, they carry them back again when the Message Item “returns” to the original item waiting in the Dispatcher.
If these items are delivered to a DropOff Object by the message-carrier-item, it will ‘return’ empty-handed back to the original Carrier Item, who carries on without those carried items.
Similarly, a message-carrier-item can collect items, and upon its 'return', pass them across to the original Carrier Item who then sets off now carrying these items.
You could use this feature to carry around a batch of items, then pass them over to a central processing location, where they are unloaded using a DropOff Object, processed at this location (item attributes changed etc.), then collected again by the message-carrier-item, and then passed back to the original Carrier Item.
Usage Notes and Limitations
You can not pass information back to the original item if you destroy the Message Item in a Splitter.
The original Item will be held in the Dispatcher forever if this happens.
You cannot allow a Message Entry to be blocked. (Model complains when this occurs).
Double clicking on a Send Message dispatcher flashes box around the Target Message Entry to assist in locating it.
Send Directed Message
This mode is similar to the Send Message Mode, except that you can direct a message to a alternative message entries.
In this Mode you nominate a Target Message Entry Object using an Attribute reference, which means the Target may be varied, depending on the value of the Attribute, which is of course changeable during a model run.
The Target option becomes available in the Object’s Menu when this Mode is selected.
When the item enters this dispatcher, the value of the attribute being referenced will resolve to an object from the _Model Objects System Label List.
The object type needs to be either an Entry in Message Entry mode, or a Portal.
If you direct a message to a portal there are two ways of receiving the message.
1. The Portal must contain a message entry called _!message.
2. You need to specify a preferred name for the Message Entry, and ensure there is a Message Entry with that name in the Portals the item is directed to.
This can be set using the Message Entry Preferred Name option which becomes available in the Object’s Menu when this Mode is selected.
Resolving the Directed Message Target
A dispatcher or Routine line sending a message to a portal will look in the following manner to attempt to find a suitable Message Entry:
- In the Portal’s subsystem using the Message Entry Preferred Name.
- In a Portal with the option “Handles Parent Messages/Broadcasts, using the Message Entry Preferred Name.
- In the Portal’s subsystem looking for a Message Entry with the same name as the sending dispatcher/change object.
- In a Portal with the option “Handles Parent Messages/Broadcasts, using the same name as the sending dispatcher/change object..
- In the Portal’s subsystem looking for a Message Entry using the default entry name (_!message).
- In a Portal with the option “Handles Parent Messages/Broadcasts, using the default entry name (_!message).
This enables
- Many message types to be directed at a portal and then individually handled within via separate entries.
- Message handling to be encapsulated in a hidden portal (must be called _!message) or use the Handles Parent Messages/Broadcasts Option, rather than having to have message entries/flows right at the top portal, which may be visible to end users.
Message Dispatcher event order
If a message item triggered any broadcasts AND the message item did not enter and leave in the same thread (ie: any capacity in the message item thread) then when the message item went into its exit, it was possible that the broadcasts would be processed before the original item tried to leave the dispatcher.
For this case, priority is given to moving the original item out of the dispatcher before any broadcast events are processed.
Directed Message for Carried Items
In this mode a dispatcher will send a message for every item that entering item is carrying.
This enables processing of statistics, inspection of carried items etc. to be performed without the overhead of dropping off all the carried items then picking them all up again using DropOff and PickUp Objects.
Note that if the dispatcher contains more than one item, performance will be reduced according to the number of carried items by the items in the dispatcher.
Send Scoped Broadcast
This mode enables a dispatcher to send a specific broadcast to a hierarchy of subsystems.
The top of the hierarchy is specified by using an Attribute that resolves to a Portal that has been included in the _Model Objects System Label List.
The broadcast is scoped to the subsystem under the object specified by the Target, which can be an Attribute reference, making the location variable.
If an index of 0 is used, the broadcast is sent globally. However if possible use a scope to make your model scalable.
Unlike a Change object broadcast, the broadcast is sent immediately, whilst the item waits in the dispatcher.
The item only leaves the dispatcher once all listening entries have produced their broadcast items and they have flowed as far as they can before encountering capacity.
Wait for Items to Exit Option
This option instructs the Dispatcher to hold on to the Item sending the broadcast until all broadcast items enter an Exit object.
Normally, the item waits at the dispatcher only until the initial thread from each broadcast entry completes (items reach a point of capacity).
This option is useful when you want to guarantee that all broadcasts have been completely processed before the item leaves the dispatcher, even if the processing of the broadcast takes non zero time or involves activities beyond a single thread (eg: pauseable zero delays, other broadcasts).
A modeller can now be assured that all listeners for a broadcast have received and had a chance to process it without having to put an explicit delay in the originating items path.
Send Dynamic Broadcast
In this mode a dispatcher sends a broadcast to a scope set by a reference, as for the normal broadcast.
Unlike the normal broadcast, the type of broadcast sent is determined dynamically by another reference.
This reference should be set to an attribute which has a valid broadcast label index, to identify which broadcast type to send.
Modellers should use this mode only where absolutely necessary as PL will not identify the dispatcher as a broadcast source since the type of broadcast sent is indeterminate at edit time.
It can make a model difficult to understand and debug.
Document your intent when using it.
Wait For Specific Release
In this mode Dispatchers can be set to hold items until there is a message sent to have a specific Item Released.
Items entering the dispatcher wait there until the routine operation "Release Item" is used to release them from the dispatcher.
The "Release Item" routine operation takes 2 parameters, Item Index and Scope Panel.
- Item Index
The Item ID of the item you want released from the dispatcher
- Scope Panel
If non-zero, this specifies a dynamic panel which will define the dynamic scope under which the release will work.
If zero, the release will work for any dispatcher in the model. Using this value cuts down the search space in looking for dispatchers to release the selected item from.
The operation sets a target attribute to 1 if the item was found and released, otherwise it sets the target to 0, so you can learn whether the item was found or not.
Restart Engine/Continue
This mode is only made available for Dispatchers located within an Application Panel.
Dispatchers in this mode restart the model engine whilst retaining the item within them.
ALL OTHER ITEMS in the model are deleted - the run is stopping and restarting at time = 0, but the item at the dispatcher "survives" the restart and can continue through its flow.
To enable the dynamic object mode, the Dispatcher "Enable Edit Command Table" option must be selected.
This option is only available once the dispatcher is in "Restart Engine/Continue" mode.
To enable the dynamic object mode with a Restart Engine/Continue Dispatcher, this mode causes another Option to appear in the Object Edit Menu called Table.
Here you can make a reference to a table that will be used for the generation and manipulation of Objects.
The instruction in this table are read and carried out upon restarting after the Model Run has stopped.
Dispatcher Object Editing
The following Object Editing options are available in all Modes:
- Direction
Sets the direction in which Items will queue up. (Left to Right, Right to Left, Up to Down or Down to Up).
- Capacity
Sets the Item holding capacity of the dispatcher.
- Screen Length
Sets the number of Items shown on the screen, others are indicated by a number, as for a queue.
Dispatcher Options
The following options are available for Dispatchers - some only in specific modes:
Show Overflow
This option displays the overflow box when the number of items in the dispatcher exceeds the screen display length.
The box displays the number of extra items not visible.
The full occupancy value of a dispatcher is thus the sum of this overflow figure, and the number of visible items.
If this Option is not selected, the number of Non-Visible items is not displayed.
Look Through in Lookahead
This Dispatcher option is for advanced Track modelling use.
It enables a modeller to look past a capacity object during lookahead but have that object assert its capacity on the item when the item actually moves through it.
Used together with the LoopDelayOverride attribute, this option enables a dispatcher in a portal on a track network to "catch" a train that is testing viability of routes on the track network in lookahead but at the same time, needs to respect and wait for loop delays before it can leave the portal.
In previous versions, it wasn't possible for a route to be assigned and tested in lookahead within a portal that is using loop delays.
The engine would give an error because an item at a capacity object before the route assignment could not hold a section in loop delay since no commitment to the route had been made.
Required when you have train items exiting a portal set to Does Loop Delays and you want to use the table-based multiple choice Route Assignment method.
In such a case you need to perform a Track Lookahead to find out by what route the train can leave.
But in order for a Portal Loop Delay to work as required, the train item must be capable of being held at a capacity object.
The support comes with this dispatcher when it is placed before a Portal Exit.
When an item performs a TestEnter on it, the dispatcher does not just accept the item (like any other object with available capacity), but instead propagates this TestEnter to the Portal Exit, which fowards a track lookahead thread, allowing you the Change Object Route Assignment to inspect the network.
Show BC/message icon during run
You can choose to have the little icons in the bottom left of the Message and Broadcast Dispatchers display during a run.
Dont Copy Back Message Item
For Send Message and Send Directed Message Dispatchers.
When this is selected, the attributes/carried items of a destroyed message item are NOT copied back to the original item when it leaves the dispatcher.
Wait for items to exit
This option is for Send Scoped Broadcast dispatchers only.
Turned on, the item sending the broadcast waits in the dispatcher until all broadcast items enter an exit. Normally, the item waits at the dispatcher only until the initial thread from each broadcast entry completes (items reach a point of capacity).
Enable Edit Command Table
To enable the dynamic object mode with a Restart Engine/Continue Dispatcher, this mode causes an option called Table, to appear in the Object Edit Menu.
Here you can make a reference to a table that will be used for the generation and manipulation of Objects.
The instruction in this table are read and carried out upon restarting after the Model Run has stopped.
Refer to Editing Object Properties for information about editing properties common to all objects.
Dispatcher Articles
- Sending directed messages to an Entry specified by name
- Directed messages sent to high level portals
- Wait/Release Dispatchers
- Dispatcher Options
Dispatcher Object Frequently Asked Questions