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().

Field Summary

Fields

Modifier and Type	Field and Description
(package private) EtAttachment	att Attachment to ET system used to make, get, put, and dump events.
(package private) org.jlab.coda.et.system.AttachmentLocal	attLocal Local attachment to ET system used to make, get, put, and dump events.
(package private) byte[]	byteArray Array used in newEvents(), getEvents(), putEvents(), or dumpEvents() for any purpose.
(package private) int	count Number of events asked for in newEvents() or getEvents().
(package private) int	eventCount Number of valid events when getting event array for newEvents and getEvents.
(package private) int	group Group number from which to get events in newEvents().
(package private) EtEventImpl[]	holdEvents Place to store references to events being put/dumped using JNI with local calls.
(package private) int	length When doing put/dumpEvents, number of events to put/dump.
(package private) EtContainer.MethodType	method The method this container is set to deal with.
(package private) int	microSec Timeout in microseconds used when obtaining events with newEvents() or getEvents().
(package private) org.jlab.coda.et.enums.Mode	mode Mode used to obtain events with newEvents() or getEvents().
(package private) org.jlab.coda.et.enums.Modify	modify Modify used to obtain events with getEvents().
(package private) int	offset When doing put/dumpEvents, offset into event array arg.
(package private) EtEventImpl[]	putDumpEvents Reference to events being put/dumped using normal calls.
(package private) EtEventImpl[]	realEvents Actual ET events with buffers/real memory.
(package private) int	size Size in bytes of events asked for in newEvents().

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
(package private) void	adjustByteArraySize(int neededBytes) Make sure the byte array has at least the given amount of bytes.
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.
(package private) void	holdNewEvents(EtEventImpl[] evs) Take the new events obtained in EtSystem.newEvents(EtContainer) or EtSystem.getEvents(EtContainer) and assign them to local storage.
(package private) void	holdNewEvents(EtEventImpl[] evs, int len) Take the new events obtained in EtSystem.newEvents(EtContainer) or EtSystem.getEvents(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

Field Detail

method

EtContainer.MethodType method

The method this container is set to deal with.

eventCount

int eventCount

Number of valid events when getting event array for newEvents and getEvents.

realEvents

EtEventImpl[] realEvents

Actual ET events with buffers/real memory.

putDumpEvents

EtEventImpl[] putDumpEvents

Reference to events being put/dumped using normal calls. Actual events were originally placed in either jniEvents or realEvents.

holdEvents

EtEventImpl[] holdEvents

Place to store references to events being put/dumped using JNI with local calls.

offset

int offset

When doing put/dumpEvents, offset into event array arg.

length

int length

When doing put/dumpEvents, number of events to put/dump.

att

EtAttachment att

Attachment to ET system used to make, get, put, and dump events.

attLocal

org.jlab.coda.et.system.AttachmentLocal attLocal

Local attachment to ET system used to make, get, put, and dump events.

byteArray

byte[] byteArray

Array used in newEvents(), getEvents(), putEvents(), or dumpEvents() for any purpose. Defined here to prevent allocation each time method is called. Reduces generated garbage. Will be expanded as needed.

modify

org.jlab.coda.et.enums.Modify modify

Modify used to obtain events with getEvents().

mode

org.jlab.coda.et.enums.Mode mode

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

microSec

int microSec

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

count

int count

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

size

int size

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

group

int group

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

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;

holdNewEvents

void holdNewEvents(EtEventImpl[] evs)

Take the new events obtained in EtSystem.newEvents(EtContainer) or EtSystem.getEvents(EtContainer) and assign them to local storage.

Parameters:

evs - array of incoming events. This array will be realEvents unless it is from a jni method call, in which case we store it in the jniEvents array.

holdNewEvents

void holdNewEvents(EtEventImpl[] evs,
                   int len)

Take the new events obtained in EtSystem.newEvents(EtContainer) or EtSystem.getEvents(EtContainer) and assign them to local storage.

Parameters:

evs - array of incoming events. This array will be realEvents unless it is from a jni method call, in which case we store it in the jniEvents array.

len - number of valid events in array (starting at 0).

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.

adjustByteArraySize

void adjustByteArraySize(int neededBytes)

Make sure the byte array has at least the given amount of bytes.

Parameters:

neededBytes - needed amount of bytes in byte array.

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.