ModuleAdapter

java.lang.Object
- org.jlab.coda.emu.modules.ModuleAdapter

All Implemented Interfaces:

EmuModule, CODAStateMachine, StatedObject

Direct Known Subclasses:

Dummy, EventRecording, FarmController, FastEventBuilder, RocFixedRateSimulation, RocSimulation, ToFile, TsFixedRateSimulation, TsSimulation
```
public class ModuleAdapter
extends java.lang.Object
implements EmuModule
```
This class contains boilerplate code for implementing a module.

Author:

timmer Mar 20, 2014

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`(package private) class`	`ModuleAdapter.RateCalculatorThread` This class defines a thread that makes instantaneous rate calculations once every few seconds.

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.Map<java.lang.String,java.lang.String>`	`attributeMap` Map containing attributes of this module given in config file.
`protected int`	`avgEventSize` Average-sized built event in bytes.
`protected Emu`	`emu` Emu this module belongs to.
`protected EmuEventNotify`	`endCallback` Object used by Emu to be notified of END event arrival.
`protected boolean`	`epThreadsSetInConfig` Were the number of event producing threads explicitly set in config file?
`protected java.util.concurrent.atomic.AtomicReference<java.lang.String>`	`errorMsg` Possible error message.
`protected long`	`eventCountTotal` Total number of evio events written to the outputs.
`protected int`	`eventProducingThreads` Number of event producing threads in operation.
`protected float`	`eventRate` Instantaneous event rate in Hz over the last time period of length `statGatheringPeriod`.
`protected int`	`goodChunk_X_EtBufSize` For ET output channels, a suggested value of chunk * ET-buffer-size (bytes) which would be a good match for the current size events being built.
`protected int`	`id` ID number of this module obtained from config file.
`protected int[]`	`inputChanLevels` Array containing, for each input channel, the percentage (0-100) of filled ring space.
`protected java.lang.String[]`	`inputChanNames` Array containing names for each input channel.
`protected int`	`inputChannelCount` Number of output channels.
`protected java.util.ArrayList<DataChannel>`	`inputChannels` ArrayList of DataChannel objects for this module that are inputs.
`protected Logger`	`logger` Logger used to log messages to debug console.
`protected int`	`maxEventSize` Maximum-sized built event in bytes.
`protected int`	`minEventSize` Minimum-sized built event in bytes.
`protected CODAStateIF`	`moduleState` State of this module.
`protected java.lang.String`	`name` Name of this module.
`protected int[]`	`outputChanLevels` Array containing, for each output channel, the percentage (0-100) of filled ring space.
`protected java.lang.String[]`	`outputChanNames` Array containing names for each output channel.
`protected int`	`outputChannelCount` Number of output channels.
`protected java.util.ArrayList<DataChannel>`	`outputChannels` ArrayList of DataChannel objects that are outputs.
`protected java.nio.ByteOrder`	`outputOrder` Do we produce big or little endian output in ByteBuffers?
`protected boolean`	`paused` User hit PAUSE button if `true`.
`protected EmuEventNotify`	`prestartCallback` Object used by Emu to be notified of PRESTART event arrival.
`protected java.lang.Thread`	`RateCalculator` Thread to calculate event and data rates.
`protected boolean`	`representStatistics` If `true`, this module's statistics represents that of the EMU.
`protected static int`	`statGatheringPeriod` Targeted time period in milliseconds over which instantaneous rates will be calculated.
`protected Statistics`	`statistics` Handle histogram of event build times.
`protected boolean`	`timeStatsOn` If true, collect statistics on event build times (performance drag).
`protected int[]`	`timeToBuild` Histogram of time to build 1 event in nanoseconds (metadata in first 5 elements).
`protected long`	`wordCountTotal` Sum of the sizes, in 32-bit words, of all evio events written to the outputs.
`protected float`	`wordRate` Instantaneous word rate in Hz over the last time period of length `statGatheringPeriod`.

Constructor Summary

Constructors
Constructor and Description
`ModuleAdapter(java.lang.String name, Emu emu)` Default constructor for fake TS.
`ModuleAdapter(java.lang.String name, java.util.Map<java.lang.String,java.lang.String> attributeMap, Emu emu)` Constructor creates a new EventRecording instance.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addInputChannels(java.util.ArrayList<DataChannel> input_channels)` Add the given input channels to this EmuModule object.
`void`	`addOutputChannels(java.util.ArrayList<DataChannel> output_channels)` Add the given output channels to this EmuModule object.
`void`	`adjustStatistics(long eventsAdded, long wordsAdded)` Adjust the event count and word count reported by this module to run control by added the given numbers.
`void`	`clearChannels()` Remove all channels from this EmuModule object.
`void`	`download()` This method implements the DOWNLOAD transition of the CODA run control state machine.
`void`	`end()` This method implements the END transition of the CODA run control state machine.
`protected void`	`eventToOutputChannel(RingItem itemOut, DataChannel channel, int ringNum)` This method is used to place an item onto a specified ring buffer of a single, specified output channel.
`protected void`	`eventToOutputChannel(RingItem itemOut, int channelNum, int ringNum)` This method is used to place an item onto a specified ring buffer of a single, specified output channel.
`java.lang.String`	`getAttr(java.lang.String name)` Get the named attribute from the config file of this module.
`EmuEventNotify`	`getEndCallback()` This method gets the callback object previously registered by the caller used to notify upon the arrival of an END event.
`java.lang.String`	`getError()` Get any available error information.
`int`	`getEventProducingThreadCount()` Get the number of threads which produce events to be placed in output channels.
`java.util.ArrayList<DataChannel>`	`getInputChannels()` Get the input channels of this EmuModule object.
`int[]`	`getInputLevels()` Get array containing the relative fill level (0-100) of each input channel's ring.
`java.lang.String[]`	`getInputNames()` Get the names of the input channels of this EmuModule object.
`int`	`getIntAttr(java.lang.String name)` Get the named attribute, as an integer, from the config file of this module.
`int`	`getInternalRingCount()` Get the number of items this EmuModule object has in its internal rings.
`java.util.ArrayList<DataChannel>`	`getOutputChannels()` Get the output channels of this EmuModule object.
`int[]`	`getOutputLevels()` Get array containing the relative fill level (0-100) of each output channel's ring(s).
`java.lang.String[]`	`getOutputNames()` Get the names of the output channels of this EmuModule object.
`java.nio.ByteOrder`	`getOutputOrder()` Get the byte order of the module's output.
`EmuEventNotify`	`getPrestartCallback()` This method gets the callback object previously registered by the caller used to notify upon the arrival of a PRESTART event.
`java.lang.Object[]`	`getStatistics()` Get the output statistics of this EmuModule object.
`void`	`go()` This method implements the GO transition of the CODA run control state machine.
`java.lang.String`	`name()` Get the name of the module
`void`	`pause()` This method implements the PAUSE transition of the CODA run control state machine.
`void`	`prestart()` This method implements the PRESTART transition of the CODA run control state machine.
`void`	`registerEndCallback(EmuEventNotify callback)` This method allows for setting a object used to notify the caller when an END event has arrived (or any other occurrence for that matter).
`void`	`registerPrestartCallback(EmuEventNotify callback)` This method allows for setting a object used to notify the caller when a PRESTART event has arrived (or any other occurrence for that matter).
`boolean`	`representsEmuStatistics()` If an EMU has more than one module, which module's statistics represent the EMU as a whole needs to be determined.
`void`	`reset()` This method implements the RESET transition of the CODA run control state machine.
`CODAStateIF`	`state()` Get the state of this object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - id
```
protected int id
```
    ID number of this module obtained from config file.
  - eventProducingThreads
```
protected int eventProducingThreads
```
    Number of event producing threads in operation. Each must match up with its own output channel ring buffer.
  - epThreadsSetInConfig
```
protected boolean epThreadsSetInConfig
```
    Were the number of event producing threads explicitly set in config file?
  - name
```
protected final java.lang.String name
```
    Name of this module.
  - errorMsg
```
protected java.util.concurrent.atomic.AtomicReference<java.lang.String> errorMsg
```
    Possible error message. reset() sets it back to null. Making this an atomically settable String ensures that only 1 thread at a time can change its value. That way it's only set once per error.
  - emu
```
protected final Emu emu
```
    Emu this module belongs to.
  - logger
```
protected final Logger logger
```
    Logger used to log messages to debug console.
  - moduleState
```
protected volatile CODAStateIF moduleState
```
    State of this module.
  - attributeMap
```
protected final java.util.Map<java.lang.String,java.lang.String> attributeMap
```
    Map containing attributes of this module given in config file.
  - inputChannels
```
protected java.util.ArrayList<DataChannel> inputChannels
```
    ArrayList of DataChannel objects for this module that are inputs. It is only modified in the addInputChannels(ArrayList) and clearChannels() methods and then only by the main EMU thread in prestart. However, other threads (such as the EMU's statistics reporting thread) call methods which use its iterator or getters.
  - outputChannels
```
protected java.util.ArrayList<DataChannel> outputChannels
```
    ArrayList of DataChannel objects that are outputs. Only modified in prestart but used during go when writing module output.
  - inputChannelCount
```
protected int inputChannelCount
```
    Number of output channels.
  - outputChannelCount
```
protected int outputChannelCount
```
    Number of output channels.
  - paused
```
protected boolean paused
```
    User hit PAUSE button if true.
  - endCallback
```
protected EmuEventNotify endCallback
```
    Object used by Emu to be notified of END event arrival.
  - prestartCallback
```
protected EmuEventNotify prestartCallback
```
    Object used by Emu to be notified of PRESTART event arrival.
  - outputOrder
```
protected java.nio.ByteOrder outputOrder
```
    Do we produce big or little endian output in ByteBuffers?
  - inputChanLevels
```
protected int[] inputChanLevels
```
    Array containing, for each input channel, the percentage (0-100) of filled ring space.
  - outputChanLevels
```
protected int[] outputChanLevels
```
    Array containing, for each output channel, the percentage (0-100) of filled ring space.
  - inputChanNames
```
protected java.lang.String[] inputChanNames
```
    Array containing names for each input channel.
  - outputChanNames
```
protected java.lang.String[] outputChanNames
```
    Array containing names for each output channel.
  - eventCountTotal
```
protected long eventCountTotal
```
    Total number of evio events written to the outputs.
  - wordCountTotal
```
protected long wordCountTotal
```
    Sum of the sizes, in 32-bit words, of all evio events written to the outputs.
  - eventRate
```
protected float eventRate
```
    Instantaneous event rate in Hz over the last time period of length statGatheringPeriod.
  - wordRate
```
protected float wordRate
```
    Instantaneous word rate in Hz over the last time period of length statGatheringPeriod.
  - maxEventSize
```
protected int maxEventSize
```
    Maximum-sized built event in bytes.
  - minEventSize
```
protected int minEventSize
```
    Minimum-sized built event in bytes.
  - avgEventSize
```
protected int avgEventSize
```
    Average-sized built event in bytes.
  - goodChunk_X_EtBufSize
```
protected int goodChunk_X_EtBufSize
```
    For ET output channels, a suggested value of chunk * ET-buffer-size (bytes) which would be a good match for the current size events being built.
  - timeToBuild
```
protected int[] timeToBuild
```
    Histogram of time to build 1 event in nanoseconds (metadata in first 5 elements).
  - statGatheringPeriod
```
protected static final int statGatheringPeriod
```
    Targeted time period in milliseconds over which instantaneous rates will be calculated.
    
    See Also:
    
    Constant Field Values
  - representStatistics
```
protected boolean representStatistics
```
    If true, this module's statistics represents that of the EMU.
  - timeStatsOn
```
protected boolean timeStatsOn
```
    If true, collect statistics on event build times (performance drag).
  - statistics
```
protected Statistics statistics
```
    Handle histogram of event build times.
  - RateCalculator
```
protected java.lang.Thread RateCalculator
```
    Thread to calculate event and data rates.
- Constructor Detail
  - ModuleAdapter
```
public ModuleAdapter(java.lang.String name,
                     Emu emu)
```
    Default constructor for fake TS.
    
    Parameters:
    
    name - name of module.
    
    emu - Emu this module belongs to.
  - ModuleAdapter
```
public ModuleAdapter(java.lang.String name,
                     java.util.Map<java.lang.String,java.lang.String> attributeMap,
                     Emu emu)
```
    Constructor creates a new EventRecording instance.
    
    Parameters:
    
    name - name of module
    
    attributeMap - map containing attributes of module
    
    emu - Emu this module belongs to.
- Method Detail
  - eventToOutputChannel
```
protected void eventToOutputChannel(RingItem itemOut,
                                    int channelNum,
                                    int ringNum)
                             throws java.lang.InterruptedException
```
    This method is used to place an item onto a specified ring buffer of a single, specified output channel.
    
    Parameters:
    
    itemOut - the event to place on output channel
    
    channelNum - index of output channel to place item on
    
    ringNum - index of output channel ring buffer to place item on
    
    Throws:
    
    java.lang.InterruptedException - it thread interrupted.
  - eventToOutputChannel
```
protected void eventToOutputChannel(RingItem itemOut,
                                    DataChannel channel,
                                    int ringNum)
                             throws java.lang.InterruptedException
```
    This method is used to place an item onto a specified ring buffer of a single, specified output channel.
    
    Parameters:
    
    itemOut - the event to place on output channel
    
    channel - which output channel to place item on
    
    ringNum - index of output channel ring buffer to place item on
    
    Throws:
    
    java.lang.InterruptedException - it thread interrupted.
  - getInputNames
```
public java.lang.String[] getInputNames()
```
    Get the names of the input channels of this EmuModule object. Used in gathering statistics.
    
    Specified by:
    
    getInputNames in interface EmuModule
    
    Returns:
    
    array containing names of input channels of this EmuModule object
  - getOutputNames
```
public java.lang.String[] getOutputNames()
```
    Get the names of the output channels of this EmuModule object. Used in gathering statistics.
    
    Specified by:
    
    getOutputNames in interface EmuModule
    
    Returns:
    
    array containing names of output channels of this EmuModule object
  - getOutputLevels
```
public int[] getOutputLevels()
```
    Get array containing the relative fill level (0-100) of each output channel's ring(s). Used in gathering statistics.
    
    Specified by:
    
    getOutputLevels in interface EmuModule
    
    Returns:
    
    array containing relative fill level (0-100) of output channels' ring(s).
  - getInputLevels
```
public int[] getInputLevels()
```
    Get array containing the relative fill level (0-100) of each input channel's ring. Used in gathering statistics.
    
    Specified by:
    
    getInputLevels in interface EmuModule
    
    Returns:
    
    array containing relative fill level (0-100) of input channels' ring(s).
  - go
```
public void go()
        throws CmdExecException
```
    This method implements the GO transition of the CODA run control state machine.
    
    Specified by:
    
    go in interface CODAStateMachine
    
    Throws:
    
    CmdExecException - if error during command execution.
  - end
```
public void end()
         throws CmdExecException
```
    This method implements the END transition of the CODA run control state machine.
    
    Specified by:
    
    end in interface CODAStateMachine
    
    Throws:
    
    CmdExecException - if error during command execution.
  - pause
```
public void pause()
```
    This method implements the PAUSE transition of the CODA run control state machine.
    
    Specified by:
    
    pause in interface CODAStateMachine
  - prestart
```
public void prestart()
              throws CmdExecException
```
    This method implements the PRESTART transition of the CODA run control state machine.
    
    Specified by:
    
    prestart in interface CODAStateMachine
    
    Throws:
    
    CmdExecException - if error during command execution.
  - download
```
public void download()
              throws CmdExecException
```
    This method implements the DOWNLOAD transition of the CODA run control state machine.
    
    Specified by:
    
    download in interface CODAStateMachine
    
    Throws:
    
    CmdExecException - if error during command execution.
  - reset
```
public void reset()
```
    This method implements the RESET transition of the CODA run control state machine.
    
    Specified by:
    
    reset in interface CODAStateMachine
  - registerEndCallback
```
public void registerEndCallback(EmuEventNotify callback)
```
    This method allows for setting a object used to notify the caller when an END event has arrived (or any other occurrence for that matter).
    
    Specified by:
    
    registerEndCallback in interface CODAStateMachine
    
    Parameters:
    
    callback - object used for notifying caller.
  - getEndCallback
```
public EmuEventNotify getEndCallback()
```
    This method gets the callback object previously registered by the caller used to notify upon the arrival of an END event.
    
    Specified by:
    
    getEndCallback in interface CODAStateMachine
    
    Returns:
    
    object used for notifying caller.
  - registerPrestartCallback
```
public void registerPrestartCallback(EmuEventNotify callback)
```
    This method allows for setting a object used to notify the caller when a PRESTART event has arrived (or any other occurrence for that matter).
    
    Specified by:
    
    registerPrestartCallback in interface CODAStateMachine
    
    Parameters:
    
    callback - object used for notifying caller.
  - getPrestartCallback
```
public EmuEventNotify getPrestartCallback()
```
    This method gets the callback object previously registered by the caller used to notify upon the arrival of a PRESTART event.
    
    Specified by:
    
    getPrestartCallback in interface CODAStateMachine
    
    Returns:
    
    object used for notifying caller.
  - state
```
public CODAStateIF state()
```
    Get the state of this object.
    
    Specified by:
    
    state in interface StatedObject
    
    Returns:
    
    the state of this object
  - getError
```
public java.lang.String getError()
```
    Get any available error information.
    
    Specified by:
    
    getError in interface StatedObject
    
    Returns:
    
    any available error information; null if none
  - getAttr
```
public java.lang.String getAttr(java.lang.String name)
                         throws DataNotFoundException
```
    Get the named attribute from the config file of this module.
    
    Specified by:
    
    getAttr in interface EmuModule
    
    Parameters:
    
    name - name of the module's config file attribute.
    
    Returns:
    
    string value of the attribute
    
    Throws:
    
    DataNotFoundException - if attribute not found.
  - getIntAttr
```
public int getIntAttr(java.lang.String name)
               throws DataNotFoundException,
                      java.lang.NumberFormatException
```
    Get the named attribute, as an integer, from the config file of this module.
    
    Specified by:
    
    getIntAttr in interface EmuModule
    
    Parameters:
    
    name - name of the module's config file attribute.
    
    Returns:
    
    integer value of the attribute
    
    Throws:
    
    DataNotFoundException - if attribute not found.
    
    java.lang.NumberFormatException - if attribute cannot be interpreted as an integer
  - name
```
public java.lang.String name()
```
    Get the name of the module
    
    Specified by:
    
    name in interface EmuModule
    
    Returns:
    
    module name
  - getInternalRingCount
```
public int getInternalRingCount()
```
    Get the number of items this EmuModule object has in its internal rings.
    
    Specified by:
    
    getInternalRingCount in interface EmuModule
    
    Returns:
    
    number of items this EmuModule object has in its internal rings.
  - representsEmuStatistics
```
public boolean representsEmuStatistics()
```
    If an EMU has more than one module, which module's statistics represent the EMU as a whole needs to be determined. This method returns true if this module's statistics may represent the EMU as a whole. This may be specified in an EMU's xml configuration file by including the attribute statistics="on" in the module definition.
    
    Specified by:
    
    representsEmuStatistics in interface EmuModule
    
    Returns:
    
    true if this module's statistics represents the EMU, else false.
  - getStatistics
```
public java.lang.Object[] getStatistics()
```
    Get the output statistics of this EmuModule object. The output statistics consists of an array of 2 Longs, 2 Floats, 4 Integers, and 1 int array:
    1. event count (Long)
    2. word count (Long)
    3. event rate in Hz (Float
    4. data rate in kBytes/sec (Float)
    5. max event size in bytes (Integer) if module is an EB
    6. min event size in bytes (Integer) if module is an EB
    7. avg event size in bytes (Integer) if module is an EB
    8. suggested value for chunk*EtBufSize (Integer) if have ET output channel
    9. if EB and switched on, histogram of time to build 1 event in nanoseconds (int array)
    Specified by:
    
    getStatistics in interface EmuModule
    
    Returns:
    
    array of objects containing in order: 1) event count (Long), 2) word count (Long), 3) event rate(Float), 4) data rate (Float), optionally 5) max event byte size (Integer), 6) min event byte size (Integer), 7) average event byte size (Integer), and 8) suggested value for chunk*EtBufSize (Integer) if have ET output channel, or 9) histogram of time to build 1 event in nanosec (int array), or null if no statistics reported for this module.
  - adjustStatistics
```
public void adjustStatistics(long eventsAdded,
                             long wordsAdded)
```
    Adjust the event count and word count reported by this module to run control by added the given numbers. This is necessary in the file output channel when the limit of the disk partition is reached and physics events must be thrown away after passing through the module.
    
    Specified by:
    
    adjustStatistics in interface EmuModule
    
    Parameters:
    
    eventsAdded - number of events to be added the event count
    
    wordsAdded - number of words to be added the word count
  - addInputChannels
```
public void addInputChannels(java.util.ArrayList<DataChannel> input_channels)
```
    Add the given input channels to this EmuModule object.
    
    Specified by:
    
    addInputChannels in interface EmuModule
    
    Parameters:
    
    input_channels - the input channels to add to this EmuModule object
  - addOutputChannels
```
public void addOutputChannels(java.util.ArrayList<DataChannel> output_channels)
```
    Add the given output channels to this EmuModule object.
    
    Specified by:
    
    addOutputChannels in interface EmuModule
    
    Parameters:
    
    output_channels - the output channels to add to this EmuModule object
  - getInputChannels
```
public java.util.ArrayList<DataChannel> getInputChannels()
```
    Get the input channels of this EmuModule object.
    
    Specified by:
    
    getInputChannels in interface EmuModule
    
    Returns:
    
    ArrayList containing the input channels of this EmuModule object
  - getOutputChannels
```
public java.util.ArrayList<DataChannel> getOutputChannels()
```
    Get the output channels of this EmuModule object.
    
    Specified by:
    
    getOutputChannels in interface EmuModule
    
    Returns:
    
    ArrayList containing the output channels of this EmuModule object
  - clearChannels
```
public void clearChannels()
```
    Remove all channels from this EmuModule object.
    
    Specified by:
    
    clearChannels in interface EmuModule
  - getEventProducingThreadCount
```
public int getEventProducingThreadCount()
```
    Get the number of threads which produce events to be placed in output channels.
    
    Specified by:
    
    getEventProducingThreadCount in interface EmuModule
    
    Returns:
    
    number of threads which produce events to be placed in output channels.
  - getOutputOrder
```
public java.nio.ByteOrder getOutputOrder()
```
    Get the byte order of the module's output. Defaults to big endian.
    
    Specified by:
    
    getOutputOrder in interface EmuModule
    
    Returns:
    
    byte order of the module's output.

Class ModuleAdapter

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

id

eventProducingThreads

epThreadsSetInConfig

name

errorMsg

emu

logger

moduleState

attributeMap

inputChannels

outputChannels

inputChannelCount

outputChannelCount

paused

endCallback

prestartCallback

outputOrder

inputChanLevels

outputChanLevels

inputChanNames

outputChanNames

eventCountTotal

wordCountTotal

eventRate

wordRate

maxEventSize

minEventSize

avgEventSize

goodChunk_X_EtBufSize

timeToBuild

statGatheringPeriod

representStatistics

timeStatsOn

statistics

RateCalculator

Constructor Detail

ModuleAdapter

ModuleAdapter

Method Detail

eventToOutputChannel

eventToOutputChannel

getInputNames

getOutputNames

getOutputLevels

getInputLevels

go

end

pause

prestart

download

reset

registerEndCallback

getEndCallback

registerPrestartCallback

getPrestartCallback

state

getError

getAttr

getIntAttr

name

getInternalRingCount

representsEmuStatistics

getStatistics

adjustStatistics

addInputChannels

addOutputChannels

getInputChannels

getOutputChannels

clearChannels

getEventProducingThreadCount

getOutputOrder