SimEvents®

Entity Combiner - Generate one entity per set of entities arriving simultaneously

Library

Entity Management

Description

This block generates one new entity for each set of entities arriving simultaneously at multiple input ports. The arriving entities are called component entities. They might represent different parts within a larger item, such as a header, payload, and trailer that are parts of a packet. The Entity Combiner block and its preceding blocks automatically detect when all necessary component entities are ready for the combining operation to proceed. Your parameter choices in this block determine whether other blocks can access the attributes or timers of the component entities, and whether the combining operation is reversible. Some parameter choices require uniqueness of attribute names or timer tags in the component entities.

Timeout events, if any, corresponding to the component entities are canceled during the combining operation.

Waiting for Component Entities on Multiple Paths

The Entity Combiner block has multiple entity input ports and one entity output port. The combining operation occurs when all necessary component entities are ready and the resulting entity would be able to depart. More explicitly, when all the blocks that connect to the Entity Combiner block's entity input ports have a pending entity simultaneously and the port connecting to the Entity Combiner block's entity output port is available, the Entity Combiner block accepts one entity arrival at each input port and outputs one entity. At all other times, the Entity Combiner block's input ports are unavailable.

Tip   It is typical to connect a queue or other storage block to each entity input port of the Entity Combiner block. The storage blocks provide a place for pending entities to wait for other entity paths to have pending entities. Storage blocks are especially important if multiple component entities come from a single multiple-output block, such as a Replicate or Entity Splitter block.

Managing Information When Combining Entities

The entity that departs from the Entity Combiner block can optionally carry information about the component entities that the block combines. In some applications, you might consider the information to be more important than the entities that carry it. The table below indicates how different options of the block produce different requirements and behavior regarding

• Uniqueness of attribute names among the entities at all entity input ports of the Entity Combiner block

• Uniqueness of timer tags among the entities at all entity input ports of the Entity Combiner block

• Your ability to use the departing entity to access attributes and timers from the component entities

• Your ability to split the departing entity into its components using the Entity Splitter block

Note   You can manage access to the set of attributes and the set of timers independently. The table treats attributes and timers together merely for conciseness.

Options for Managing Information When Combining Entities

If you do not select Retain structure in departing entity, you can think of the block as generating a new nonhierarchical entity, copying attribute or timer information to the new entity if necessary, and then discarding the component entities.

Ports

Entity Input Ports

Entity Output Ports

Signal Output Ports

The initial output value, which is in effect from the start of the simulation until the first update by the block, is 0.

Dialog Box

Entity Combiner Tab

Number of entity input ports

Determines how many entity input ports the block has. This parameter must be a literal value, not a variable or an expression requiring evaluation.

Retain structure in departing entity

If you select this option, the departing entity carries information about the number of component entities and which attributes and timers each component entity possesses. Such information enables you to recover the component entities using the Entity Splitter block.

Make attributes accessible in departing entity, Copy attributes to departing entity

If you select this option, you can access attributes from the component entities via the departing entity. The name of this field depends on whether you select Retain structure in departing entity.

Make timers accessible in departing entity, Copy timers to departing entity

If you select this option, you can access timers from the component entities via the departing entity. The name of this field depends on whether you select Retain structure in departing entity.

Statistics Tab

Number of entities departed

Controls the presence and behavior of the signal output port labeled #d.

Examples

• Example: Waiting to Combine Entities

• Example: Copying Timers When Combining Entities

• Example: Managing Data in Composite Entities

• Entity Combiner for Assembling Components demo

Limitations

In general, a composite entity can arrive at this block and become a component entity within a new nested composite entity. However, if you select Retain structure in departing entity, the depth of nesting is limited. This prevents the memory usage of nested composite entities from growing without bound in the case of a looped entity path.

See Also

Entity Splitter

Combining Entities

Enabled Gate

Entity Departure Counter