6.4 LegionBuffer
6.4.1 Constructors
LegionBuffer()
Parameters: None
The default constructor is for the common case; it creates an empty buffer with a LegionStorageScat storage, and default implementations of the packer, compressor, and encryptor function sets.
LegionBuffer()
Parameters: UVaL_Reference<LegionStorage>
The simple constructor wraps a default buffer around a given storage object. It uses default implementations for the packer, encryptor, and compressor.
LegionBuffer()
Parameters: LegionMetaData metadata
The meta-data based constructor creates a new empty LegionBuffer with a LegionStorageScat default storage implementation. It instantiates packer, encryptor and compressors based on the meta-data.
LegionBuffer()
Parameters: UVaL_Reference<LegionStorage>
LegionMetaData metadata
The full featured constructor wraps a specified storage in a buffer appropriate for the given meta-data, selecting the right packer meta-data, compressor, and encryptor implementations.
6.4.2 Operations on the associated LegionStorage
A LegionStorage exports member functions to read and write untyped characters from and to a logical buffer. These operations are also exported by LegionBuffer, but the user should be warned that the "better" way to put data into a buffer is through the LegionPacker interface; read() and write() will not perform appropriate data format conversions, but put_int() and get_int() will.
size_t read()
Parameters: size_t num_bytes
void *data
Reads num_bytes bytes from the buffer starting at the current location of the buffer pointer. Copies the bytes into the space pointed to by data_dest. Returns the number of bytes actually read, and positions the buffer pointer immediately after the last byte that was read. Read() will not read past the end of the buffer.
size_t write()
Parameters: size_t num_bytes
void *data
Writes num_bytes bytes pointed to by data into the buffer starting at current position of the buffer pointer (overwriting existing data). Returns the number of bytes actually written, and positions the buffer pointer immediately after the last byte that was written. Writing past the end of the buffer causes it to expand.
size_t seek()
Parameters: seek_start whence
int bytes_away
Changes the position of the buffer pointer. The whence parameter can be BEGINNING (0), CURRENT (1), or END (2), and bytes_away tells how many bytes away from whence to set the pointer. Seeking past the end of the buffer causes it to expand and to be filled with NULL bytes. Seeking to negative logical positions the buffer does not cause the buffer to expand; the buffer pointer is placed at logical position 0.
size_t size()
Parameters: None
Returns the current size of the buffer in bytes.
size_t current_byte()
Parameters: None
Returns the number of the byte to which the buffer pointer currently points. Current_byte() returns 0 when the buffer pointer is at the beginning of the buffer, and current_byte() == size() when the buffer pointer is at the end of the buffer.
char *linearize()
Parameters: int pack_metadata=0
Returns a pointer to the beginning of the buffer's data. This pointer is guaranteed to point to data that is contiguous in memory. Depending on the implementation of the LegionStorage, this function may or may not need to return a pointer to a copy of the data.
void setMetaData()
Parameters: LegionMetaData md
Sets the metadata associated with the LegionStorage.
LegionMetaData getMetaData()
Parameters: None
Returns the meta data associated with the LegionStorage. This is useful for instantiating an appropriate LegionBuffer based on a given LegionStorage.
6.4.3 Operations on the associated LegionPacker
A LegionPacker exports operations for packing and unpacking the basic C++ data types into and out of a LegionBuffer in a particular data format. A LegionPacker exports put_ZZZ() and get_ZZZ() for all ZZZ in {char, short, ushort, int, long, ulong, float, double}.
size_t put_ZZZ()
Parameters: ZZZ *source
int how_many
Assumes that source points to an array of how_many instances of type ZZZ. Copies this data into the buffer after first performing the appropriate data conversion operation if necessary and appropriate for the type of LegionPacker that is instantiated.
size_t get_ZZZ()
Parameters: ZZZ *source
int how_many
Assumes that source points to enough space for an array of how_many instances of type ZZZ. Copies the next data from the LegionBuffer into this space after first performing the appropriate data conversion operation if necessary and appropriate for the type of LegionPacker that is instantiated.
6.4.4 Operations on the associated LegionEncryptor
Since no encryption algorithms have been implemented, the current encryption operations, encrypt() and decode(), are merely placeholders until the right set of encryption operations are defined.
6.4.5 Operations on the associated LegionCompressor
Since no compression algorithms have been implemented, the current compression operations, compress() and decompress(), are merely placeholders until the right set of compression operations are defined.
6.4.6 LegionPackable
int pack()
Parameters: int unpack()
LegionBuffer &lb
LegionBuffers are themselves packable.
6.4.7 Other functions
Prints the contents of the LegionBuffer to stderr. This is done however the associated LegionStorage sees fit.
6.4.8 Naming and binding: LegionLOID
LegionLOID is intended to be a base class for LOID's that enforce a particular structure on the fields of the LOID. An LOID contains four private data members, (1) an integer that holds the type of LOID, (2) an integer that indicates how many fields the LOID contains, (3) an array field_size[] of integers that holds the sizes in bytes of the LOID fields, and (4) an array field_value[] of pointers to the field data. Currently, the only derived class is called LegionGeneralPurposeLOID, which simply exposes the protected members to the public interface.
LegionLOID() (protected)
Parameters: int ltype
Sets the type to ltype, sets all other fields to zero.
LegionLOID() (protected)
Parameters: int ltype,
short nfields
Sets the type to ltype. Sets num_fields to nfields. Allocates the field_size[] and field_value[] arrays. Sets all field_size[]'s to 0, sets all field_value[]'s to NULL.
LegionLOID() (protected)
Parameters: int ltype,
short nfields,
short *fld_size
Sets the type to ltype. Sets num_fields to nfields. Allocates the field_size[] and field_value[] arrays. Sets all field_size[]'s to the values contained in the fld_size[] array. Allocates the field_value[] entries to the right size and zeros them out. This constructor assumes the fld_size array has at least nfields elements.
LegionLOID() (protected)
Parameters: int ltype
short nfields
short *fld_size
char **fld_value
Sets the type to ltype. Sets num_fields to nfields. Allocates the field_size[] and field_value[] arrays. Sets all field_size[]'s to the values contained in the fld_size[] array. Allocates the field_value[] entries to the right size and copies the values from fld_value[] array into the field_value[] array. This constructor assumes that the fld_size[] and fld_value[] arrays have at least nfields elements, and that each fld_value[i] points to at least fld_size[i] bytes of space.
set_field_size() (protected)
Parameters: short field_num
short fsize
Sets the appropriate field_size element to fsize and makes sure that the corresponding field_value element is at least fsize bytes. If it is not, it deletes the old field_value entry and allocates a new one. Only derived classes should be allowed to call this member.
set_type() (protected)
Parameters: int new_type
Sets the type entry to be new_type. Can only be called from within the code of derived classes.
LegionLOID()
Parameters: LegionBuffer &lb
LegionLOID()
Parameters: LegionLOID &otherLOID
These two constructors are public because neither allows the caller to violate the structure of any particular type of LOID -- both just copy the LOID from the parameter, either a LegionBuffer or another LegionLOID.
Not a very useful constructor, so it prints a warning and assigns all data members to zero. Useful constructors should at least say what the type is.
Methods for getting and setting the type and all field values, by field number and field name, exist.
The ==, !=, and = operators are overloaded appropriately. An LOID is equal to another only if all fields are identical in size and value.
int is_empty()
Parameters: None
Returns 1 only if the LOID is of type UVaL_LegionLOID_type_EMPTY (zero).
int is_class()
Parameters: None
Returns 1 only if the LOID seems to refer to a class object, i.e. the instance number field is empty.
int same_class_as()
Parameters: UVaL_Reference<LegionLOID> other_loid
Returns 1 if the class_id field matches that of other_loid.
Type and num_fields are packed first, in network order. Next num_fields shorts are packed, in network order. Next, num_fields values are packed.
int unpack()
Parameters: LegionBuffer &lb
The type, num_fields, and field_size[]'s are unpacked into host order. The field_value[]'s are unpacked without switching the byte order.
Prints the contents of the LOID to stderr for debugging purposes.
[Home] [General] [Documentation] [Software] [Testbeds] [Et Cetera] [Map/Search]
|
legion@Virginia.edu
http://legion.virginia.edu/