tuple.h File Reference

The tuple is a structure that assists Views in organizing and displaying virtual views of arbitrary data. The tuple describes a piece of a segment that is viewable. We refer to this piece as a sub-segment. More...

#include "segment.h"

Go to the source code of this file.

Classes
struct	_tuple
Typedefs
typedef _tuple	Tuple
Functions
void	tuple_Init (void *(*tuple_allocate)(size_t), void(*tuple_deallocate)(void *))
	Initialize the tuple memory allocation routines. The defaults are the system malloc and free. If those are acceptable, use of this function is not necessary.
Tuple *	tuple_Create (Segment *seg, unsigned int ibegin, unsigned int iend)
	Create a tuple from its components:.
void	tuple_DeleteBorrowed (Tuple *tuple)
	Delete a borrowed tuple.
void	tuple_DeleteOwned (Tuple *tuple)
	Delete an owned tuple.
Tuple *	tuple_Copy (Tuple *tuple)
	Copy a tuple.
void	tuple_Print (Tuple *tuple)
char *	tuple_SegElPtr (Tuple *tuple, unsigned int index)
	Get a pointer to the view-able piece of a segment.
Segment *	tuple_Seg (Tuple *tuple)
	Simple accessor function for the tuple's segment address.
unsigned int	tuple_Begin (Tuple *tuple)
	Simple accessor function for the tuple's begin index.
unsigned int	tuple_End (Tuple *tuple)
	Simple accessor function for the tuple's end index.
unsigned int	tuple_SetBegin (Tuple *tuple, unsigned int begin)
unsigned int	tuple_SetEnd (Tuple *tuple, unsigned int end)
unsigned int	tuple_Length (Tuple *tuple)
	Simple accessor function for the tuple's length.
unsigned int	tuple_ShiftBegin (Tuple *tuple, unsigned int N)
	Move the begin index to the right by N positions. The begin index is always moved even if N is larger than the sub-segment length.
unsigned int	tuple_ShiftEnd (Tuple *tuple, unsigned int N)
	Move the end index to the left by N positions. The end index is always moved even if N is larger than the sub-segment length.

---

Detailed Description

The tuple is a structure that assists Views in organizing and displaying virtual views of arbitrary data. The tuple describes a piece of a segment that is viewable. We refer to this piece as a sub-segment.

Each tuple owns its segment address. When a new tuple is created it either creates the segment it references or makes a copy of it. Likewise, when a give tuple is deleted, it always deletes the segment it owns.

---

Typedef Documentation

typedef struct _tuple Tuple

Make it easier to declare Tuples.

---

Function Documentation

unsigned int tuple_Begin (  Tuple *  tuple  )

Simple accessor function for the tuple's begin index. Parameters: tuple  the tuple to access. Returns: The begin index.

Tuple* tuple_Copy (  Tuple *  tuple  )

Copy a tuple. Parameters: tuple  the tuple to copy. Returns: Tuple * A copy of the tuple argument.

Tuple* tuple_Create (  Segment *  seg, unsigned int  ibegin, unsigned int  iend )

Create a tuple from its components:. Returns: a new Tuple object/struct. Parameters: seg  the address of the segment that this tuple uses. ibegin  the beginning index of the segment to display. iend  the ending index of the segment to display. Note: iend must be greater than ibegin. The segment address must be non-zero and is assumed to already have been created or copied.

void tuple_DeleteBorrowed (  Tuple *  tuple  )

Delete a borrowed tuple. Parameters: tuple  the tuple to delete. Returns: void Note: Tuples have no tell-tale that identifies their segment as either owned or borrowed. The tell-tale is contained within the View structure and whether tuple_DeleteOwned() or tuple_DeleteBorrowed is used is handled by the View.

void tuple_DeleteOwned (  Tuple *  tuple  )

Delete an owned tuple. Parameters: tuple  the tuple to delete. Returns: void Note: Tuples have no tell-tale that identifies their segment as either owned or borrowed. The tell-tale is contained within the View structure and whether tuple_DeleteOwned() or tuple_DeleteBorrowed() is used is handled by the View.

unsigned int tuple_End (  Tuple *  tuple  )

Simple accessor function for the tuple's end index. Parameters: tuple  the tuple to access. Returns: The end index.

void tuple_Init (  void *(*  tuple_allocate)(size_t), void(*  tuple_deallocate)(void *) )

Initialize the tuple memory allocation routines. The defaults are the system malloc and free. If those are acceptable, use of this function is not necessary. Parameters: tuple_allocate  A function pointer to the allocation function you wish to use. This function must have the same semantics as the C-library malloc(): void *malloc(size_t size) tuple_deallocate  A function pointer to the de-allocation function you wish to use. The function must have the same semantics as the C-library free(): void free(void *ptr) Returns: void Note: Users of the View library should only use view_Init(). view_Init() will in turn call tuple_Init() and other necessary initializer functions to ensure that memory allocation/free is handled consistently. If tuple_Init() is not used, the allocation defaults to malloc() and the deallocation defaults to free(). For examples, look in the test directory.

unsigned int tuple_Length (  Tuple *  tuple  )

Simple accessor function for the tuple's length. Parameters: tuple  the tuple to access. Returns: The tuple's length.

void tuple_Print (  Tuple *  tuple  )

/brief Print out a tuple. This is used for understanding and debugging the view library and applications that use it. The tuple's elements and segment address are printed. /param tuple the tuple to print. /return void

Segment* tuple_Seg (  Tuple *  tuple  )

Simple accessor function for the tuple's segment address. Parameters: tuple  the tuple to access. Returns: The segment address.

char* tuple_SegElPtr (  Tuple *  tuple, unsigned int  index )

Get a pointer to the view-able piece of a segment. Returns: a character pointer to the beginning of the data array. Parameters: tuple:  a pointer to a tuple object. index  The segment index we wish the pointer to identify.

unsigned int tuple_ShiftBegin (  Tuple *  tuple, unsigned int  N )

Move the begin index to the right by N positions. The begin index is always moved even if N is larger than the sub-segment length. The reason this function behaves the way it does, is that it was meant to be used from a view method that is masking chunks of a view. The caller will want to mask N elements. And, won't really care how much each tuple has to mask. So, we mask as much as we can, if we can't mask all N elements with this one tuple, then we set ibegin == iend and return how much of N is still left to mask. Then, the caller can see there is more to do, and move on to the next tuple with the new (reduced) value of N. Note that the caller should most likely delete a tuple that returns a positive value. Returns: The amount of N left to move/mask. 0 if there is none left, we were able to mask all N positions. Parameters: tuple  the tuple to shift. N  the number of positions to shift the begin marker.

unsigned int tuple_ShiftEnd (  Tuple *  tuple, unsigned int  N )

Move the end index to the left by N positions. The end index is always moved even if N is larger than the sub-segment length. Returns: The amount of N left to move/mask. 0 if there is none left, we were able to mask all N positions. Parameters: tuple  the tuple to shift. N  the number of positions to shift the end marker.

---