org.jlab.coda.et

Class EtContainer

java.lang.Object

org.jlab.coda.et.EtContainer

public class EtContainer
extends java.lang.Object

This is a helper class to facilitate efficient java programming in making, getting, putting and dumping ET events. Designed for use with the Disruptor (ring) software package and in the emu package of CODA online software.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EtContainer.MethodType Keep track of whether we're setup to do a newEvents(), getEvents(), putEvents(), or dumpEvents().

Constructor Summary

Constructors

Constructor and Description
EtContainer(int eventSize) Constructor.
EtContainer(int count, int eventSize) Constructor specifying the number and size of internal buffers which are then created and initialized.

Method Summary

Modifier and Type	Method and Description
void	dumpEvents(org.jlab.coda.et.system.AttachmentLocal att) This method is for expert use only! Set this container up for dumping events back into an ET system.
void	dumpEvents(EtAttachment att, int offset, int length) Set this container up for dumping events back into an ET system.
EtAttachment	getAtt() Get the attachment to ET system.
org.jlab.coda.et.system.AttachmentLocal	getAttLocal() If ET is java-based in this JVM, attachment to it.
int	getCount() Get the number of events asked for in newEvents() or getEvents().
int	getEtEventSize() Get the size of ET system events in bytes.
EtEvent[]	getEventArray() Get an array containing events resulting from a call to newEvents(EtAttachment, Mode, int, int, int, int) or getEvents(EtAttachment, Mode, Modify, int, int).
EtEventImpl[]	getEventArrayLocal() Get an array containing events resulting from a call to newEvents(AttachmentLocal, int, int, int, int, int) or getEvents(AttachmentLocal, int, int, int).
int	getEventCount() Get the number of valid events resulting from a call to newEvents or getEvents.
void	getEvents(org.jlab.coda.et.system.AttachmentLocal att, int modeVal, int microSec, int count) This method is for expert use only! Set this container up for getting events from an ET system.
void	getEvents(EtAttachment att, org.jlab.coda.et.enums.Mode mode, org.jlab.coda.et.enums.Modify modify, int microSec, int count) Set this container up for getting events from an ET system.
void	getEvents(EtAttachment att, org.jlab.coda.et.enums.Mode mode, org.jlab.coda.et.enums.Modify modify, int microSec, int count, boolean allocate) Set this container up for getting events from an ET system.
int	getGroup() Get the group number from which to get events in newEvents().
EtEventImpl[]	getHoldEvents() Get the array used to store references to events being put/dumped using JNI with local calls.
int	getLastIndex() Get the index of the last valid event in the array of the events being put.
EtContainer.MethodType	getMethod() Get variable keeping track of whether we're setup to do a newEvents(), getEvents(), putEvents(), or dumpEvents().
int	getMicroSec() Get the timeout in microseconds used when obtaining events with newEvents() or getEvents().
org.jlab.coda.et.enums.Mode	getMode() Get the mode used to obtain events with newEvents() or getEvents().
int	getSize() Get the size in bytes of events asked for in newEvents().
boolean	hasEndEvent() Get whether the events being put contain the END event.
void	holdLocalEvents(EtEventImpl[] evs) This method is NOT for general use! Experts only! Take the events obtained in SystemCreate.getEvents(EtContainer) and assign them to local storage.
void	holdLocalEvents(java.util.List<EtEventImpl> list) This method is NOT for general use! Experts only! Take the new events obtained in SystemCreate.newEvents(EtContainer) and assign them to local storage.
void	newEvents(org.jlab.coda.et.system.AttachmentLocal att, int modeVal, int microSec, int count, int size, int group) This method is for expert use only! Set this container up for getting new (unused) events from a specified group of such events in an ET system.
void	newEvents(EtAttachment att, org.jlab.coda.et.enums.Mode mode, int microSec, int count, int size, int group) Set this container up for getting new (unused) events from a specified group of such events in an ET system.
void	newEvents(EtAttachment att, org.jlab.coda.et.enums.Mode mode, int microSec, int count, int size, int group, boolean allocate) Set this container up for getting new (unused) events from a specified group of such events in an ET system.
void	putEvents(org.jlab.coda.et.system.AttachmentLocal att) This method is for expert use only! Set this container up for putting (used) events back into an ET system.
void	putEvents(EtAttachment att, int offset, int length) Set this container up for putting (used) events back into an ET system.
void	setHasEndEvent(boolean index) Set whether the events being put contain the END event.
void	setLastIndex(int index) Set the index of the last valid event in the array of the events being put.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EtContainer

public EtContainer(int eventSize)
            throws org.jlab.coda.et.exception.EtException

Constructor.

Parameters:

eventSize - ET system event size in bytes.

Throws:

org.jlab.coda.et.exception.EtException - if eventSize < 1.

EtContainer

public EtContainer(int count,
                   int eventSize)
            throws org.jlab.coda.et.exception.EtException

Constructor specifying the number and size of internal buffers which are then created and initialized. If the specified size is less than the ET buffer size, it is internally set to the ET buffer size.

Parameters:

count - number of internal buffers/events.

eventSize - ET system event size in bytes.

Throws:

org.jlab.coda.et.exception.EtException - if either arg < 1.

Method Detail

getEtEventSize

public int getEtEventSize()

Get the size of ET system events in bytes.

Returns:

size of ET system events in bytes.

getAtt

public EtAttachment getAtt()

Get the attachment to ET system.

Returns:

attachment to ET system.

getAttLocal

public org.jlab.coda.et.system.AttachmentLocal getAttLocal()

If ET is java-based in this JVM, attachment to it.

Returns:

attachment to ET system if system is java-based in this JVM.

getMode

public org.jlab.coda.et.enums.Mode getMode()

Get the mode used to obtain events with newEvents() or getEvents().

Returns:

mode used to obtain events with newEvents() or getEvents().

getCount

public int getCount()

Get the number of events asked for in newEvents() or getEvents().

Returns:

number of events asked for in newEvents() or getEvents().

getSize

public int getSize()

Get the size in bytes of events asked for in newEvents().

Returns:

size in bytes of events asked for in newEvents().

getGroup

public int getGroup()

Get the group number from which to get events in newEvents().

Returns:

group number from which to get events in newEvents().

getMicroSec

public int getMicroSec()

Get the timeout in microseconds used when obtaining events with newEvents() or getEvents().

Returns:

timeout in microseconds used when obtaining events with newEvents() or getEvents().

getHoldEvents

public EtEventImpl[] getHoldEvents()

Get the array used to store references to events being put/dumped using JNI with local calls. OR containing events resulting from a local call to newEvents() or getEvents().

Returns:

array used to store references to events used with local calls.

getMethod

public EtContainer.MethodType getMethod()

Get variable keeping track of whether we're setup to do a newEvents(), getEvents(), putEvents(), or dumpEvents().

Returns:

variable keeping track of whether we're setup to do a newEvents(), getEvents(), putEvents(), or dumpEvents().

newEvents

public void newEvents(EtAttachment att,
                      org.jlab.coda.et.enums.Mode mode,
                      int microSec,
                      int count,
                      int size,
                      int group)
               throws org.jlab.coda.et.exception.EtException

Set this container up for getting new (unused) events from a specified group of such events in an ET system. Will access local C-based ET systems through JNI/shared memory, but other ET systems through sockets.

Parameters:

att - attachment object.

mode - if there are no new events available, this parameter specifies whether to wait for some by sleeping Mode.SLEEP, to wait for a set time Mode.TIMED, or to return immediately Mode.ASYNC.

microSec - the number of microseconds to wait if a timed wait is specified.

count - the number of events desired .

size - the size of events in bytes.

group - group number from which to draw new events. Some ET systems have unused events divided into groups whose numbering starts at 1. For ET system not so divided, all events belong to group 1.

Throws:

org.jlab.coda.et.exception.EtException - if arguments have bad values; if attachment object is invalid;

newEvents

public void newEvents(EtAttachment att,
                      org.jlab.coda.et.enums.Mode mode,
                      int microSec,
                      int count,
                      int size,
                      int group,
                      boolean allocate)
               throws org.jlab.coda.et.exception.EtException

Set this container up for getting new (unused) events from a specified group of such events in an ET system. Will access local C-based ET systems through JNI/shared memory, but other ET systems through sockets.

Parameters:

att - attachment object.

mode - if there are no new events available, this parameter specifies whether to wait for some by sleeping Mode.SLEEP, to wait for a set time Mode.TIMED, or to return immediately Mode.ASYNC.

microSec - the number of microseconds to wait if a timed wait is specified.

count - the number of events desired .

size - the size of events in bytes.

group - group number from which to draw new events. Some ET systems have unused events divided into groups whose numbering starts at 1. For ET system not so divided, all events belong to group 1.

allocate - if true, allocate new objects in which to store the new events.

Throws:

org.jlab.coda.et.exception.EtException - if arguments have bad values; if attachment object is invalid;

newEvents

public void newEvents(org.jlab.coda.et.system.AttachmentLocal att,
                      int modeVal,
                      int microSec,
                      int count,
                      int size,
                      int group)
               throws org.jlab.coda.et.exception.EtException

This method is for expert use only! Set this container up for getting new (unused) events from a specified group of such events in an ET system. Will access local Java-based ET systems running in the same JVM.

Parameters:

att - local attachment object.

modeVal - if there are no new events available, this parameter specifies whether to wait for some by sleeping EtConstants.sleep, to wait for a set time EtConstants.timed, or to return immediately EtConstants.async.

microSec - the number of microseconds to wait if a timed wait is specified.

count - the number of events desired .

size - the size of events in bytes.

group - group number from which to draw new events. Some ET systems have unused events divided into groups whose numbering starts at 1. For ET system not so divided, all events belong to group 1.

Throws:

org.jlab.coda.et.exception.EtException - if arguments have bad values;

getEvents

public void getEvents(EtAttachment att,
                      org.jlab.coda.et.enums.Mode mode,
                      org.jlab.coda.et.enums.Modify modify,
                      int microSec,
                      int count)
               throws org.jlab.coda.et.exception.EtException

Set this container up for getting events from an ET system. Will access local C-based ET systems through JNI/shared memory, but other ET systems through sockets.

Parameters:

att - attachment object.

mode - if there are no events available, this parameter specifies whether to wait for some by sleeping Mode.SLEEP, to wait for a set time Mode.TIMED, or to return immediately Mode.ASYNC.

modify - this specifies whether this application plans on modifying the data in events obtained Modify.ANYTHING, or only modifying headers Modify.HEADER. The default assumed ,Modify.NOTHING, means that no values are modified resulting in the events being put back into the ET system (by remote server) immediately upon being copied and that copy sent to this method's caller.

microSec - the number of microseconds to wait if a timed wait is specified.

count - the number of events desired.

Throws:

org.jlab.coda.et.exception.EtException - if arguments have bad values; if the attachment's station is GRAND_CENTRAL; if the attachment object is invalid;

getEvents

public void getEvents(EtAttachment att,
                      org.jlab.coda.et.enums.Mode mode,
                      org.jlab.coda.et.enums.Modify modify,
                      int microSec,
                      int count,
                      boolean allocate)
               throws org.jlab.coda.et.exception.EtException

Set this container up for getting events from an ET system. Will access local C-based ET systems through JNI/shared memory, but other ET systems through sockets.

Parameters:

att - attachment object.

mode - if there are no events available, this parameter specifies whether to wait for some by sleeping Mode.SLEEP, to wait for a set time Mode.TIMED, or to return immediately Mode.ASYNC.

modify - this specifies whether this application plans on modifying the data in events obtained Modify.ANYTHING, or only modifying headers Modify.HEADER. The default assumed ,Modify.NOTHING, means that no values are modified resulting in the events being put back into the ET system (by remote server) immediately upon being copied and that copy sent to this method's caller.

microSec - the number of microseconds to wait if a timed wait is specified.

count - the number of events desired.

allocate - if true, allocate new objects in which to store the new events.

Throws:

org.jlab.coda.et.exception.EtException - if arguments have bad values; if the attachment's station is GRAND_CENTRAL; if the attachment object is invalid;

getEvents

public void getEvents(org.jlab.coda.et.system.AttachmentLocal att,
                      int modeVal,
                      int microSec,
                      int count)
               throws org.jlab.coda.et.exception.EtException

This method is for expert use only! Set this container up for getting events from an ET system. Will access local Java-based ET systems running in the same JVM.

Parameters:

att - local attachment object.

modeVal - if there are no new events available, this parameter specifies whether to wait for some by sleeping EtConstants.sleep, to wait for a set time EtConstants.timed, or to return immediately EtConstants.async.

microSec - the number of microseconds to wait if a timed wait is specified.

count - the number of events desired.

Throws:

org.jlab.coda.et.exception.EtException - if arguments have bad values; if the attachment's station is GRAND_CENTRAL; if the attachment object is invalid;

putEvents

public void putEvents(EtAttachment att,
                      int offset,
                      int length)
               throws org.jlab.coda.et.exception.EtException

Set this container up for putting (used) events back into an ET system. Will access local C-based ET systems through JNI/shared memory, but other ET systems through sockets.

Parameters:

att - attachment object

offset - offset into array

length - number of array elements to put

Throws:

org.jlab.coda.et.exception.EtException - if invalid arg(s); if events are not owned by this attachment;

putEvents

public void putEvents(org.jlab.coda.et.system.AttachmentLocal att)
               throws org.jlab.coda.et.exception.EtException

This method is for expert use only! Set this container up for putting (used) events back into an ET system. Will access local Java-based ET systems running in the same JVM.

Parameters:

att - local attachment object

Throws:

org.jlab.coda.et.exception.EtException - if invalid arg(s); if events are not owned by this attachment;

dumpEvents

public void dumpEvents(EtAttachment att,
                       int offset,
                       int length)
                throws org.jlab.coda.et.exception.EtException

Set this container up for dumping events back into an ET system. Will access local C-based ET systems through JNI/shared memory, but other ET systems through sockets.

Parameters:

att - attachment object

offset - offset into array

length - number of array elements to put

Throws:

org.jlab.coda.et.exception.EtException - if invalid arg(s); if events are not owned by this attachment;

dumpEvents

public void dumpEvents(org.jlab.coda.et.system.AttachmentLocal att)
                throws org.jlab.coda.et.exception.EtException

This method is for expert use only! Set this container up for dumping events back into an ET system. Will access local Java-based ET systems running in the same JVM.

Parameters:

att - local attachment object

Throws:

org.jlab.coda.et.exception.EtException - if invalid arg(s); if events are not owned by this attachment;

holdLocalEvents

public void holdLocalEvents(java.util.List<EtEventImpl> list)

This method is NOT for general use! Experts only! Take the new events obtained in SystemCreate.newEvents(EtContainer) and assign them to local storage.

Parameters:

list - list of events which will be placed in holdEvents.

holdLocalEvents

public void holdLocalEvents(EtEventImpl[] evs)

This method is NOT for general use! Experts only! Take the events obtained in SystemCreate.getEvents(EtContainer) and assign them to local storage.

Parameters:

evs - array of events which will be placed in holdEvents.

getEventArray

public EtEvent[] getEventArray()

Get an array containing events resulting from a call to newEvents(EtAttachment, Mode, int, int, int, int) or getEvents(EtAttachment, Mode, Modify, int, int). Not all of these are valid since the returned array is a reference to a large internal array. Get the number of valid events by calling getEventCount(). Don't do anything nasty to the elements of this internal array.

Returns:

events from a newEvents() or getEvents() call; null if last call was not to either of these.

getEventArrayLocal

public EtEventImpl[] getEventArrayLocal()

Get an array containing events resulting from a call to newEvents(AttachmentLocal, int, int, int, int, int) or getEvents(AttachmentLocal, int, int, int). Not all of these are valid since the returned array is a reference to a large internal array. Get the number of valid events by calling getEventCount(). Don't do anything nasty to the elements of this internal array.

Returns:

events from a LOCAL newEvents() or getEvents() call; null if last call was not to either of these.

getEventCount

public int getEventCount()

Get the number of valid events resulting from a call to newEvents or getEvents.

Returns:

number of valid events resulting from a call to newEvents or getEvents.

getLastIndex

public int getLastIndex()

Get the index of the last valid event in the array of the events being put. Useful in CODA.

Returns:

index of the last valid event in the array of the events being put. Equals -1 if none.

setLastIndex

public void setLastIndex(int index)

Set the index of the last valid event in the array of the events being put. Useful in CODA.

Parameters:

index - index of the last valid event in the array of the events being put. Set to -1 if none.

hasEndEvent

public boolean hasEndEvent()

Get whether the events being put contain the END event.

Returns:

true if the events being put contain the END event.

setHasEndEvent

public void setHasEndEvent(boolean index)

Set whether the events being put contain the END event.

Parameters:

index - true if the events being put contain the END event.