NAME

src/pmc/structview.pmc - View pointers as C structs

DESCRIPTION

PMC class to view pointers as C structs. This includes read, write, allocate, and deallocate operations. Bounds checking is implemented where the pointer class reports a non-zero bound. Recursive definition through nesting is not supported but can be emulated by interpreting pointer or buffer elements as structs once dereferenced.

Elements are get/set using keyed access of the form [Ptr; Idx], which will interpret the Ptr PMC and lookup the Idx'th element.

Vtables and Methods

void init()

Creating an instance without an initializer is dissallowed and will throw an exception.

void init_pmc(PMC *p)

Create a new StructView for viewing buffers as described by the initializer.An initializer is an array-aggregate of integers. For example, FixedIntegerArray will work for this purpose.The first element of the initializer is interpreted as the type of the StructView. There are three supported types of view: struct, indicated with the DATATYPE_STRUCT flag; union, indicated with the DATATYPE_UNION flag; and custom, indicated with the DATATYPE_SIZED flag.The second element of the initializer is interpreted as the number of elements contained within the view.If using a custom view, the third and fourth elements are interpreted as the size and alignment in bytes respectively.The remainder of the initializer is interpreted as a description of the elements of the view. For struct and union views, elements are described by a single integer flag from datatypes.pasm, with layout being determined automatically identical to what your C compiler would have done. For custom views, elements are represented by a 3-tuple of {type, byte-offset, bit-offset}, which can be used for arbitrary layouts. Note, however, that unaligned access is only supported on unsigned integers, and even then, it is inefficient. You have been warned.Supported element types are include:

Parrot Types

INTVAL, FLOATVAL, STRING, and PMC

C-Native Types

Integer: char, uchar, short, ushort, int, uint, long, ulong, longlong (*), and ulonglong (*) Float: float, double, longdouble PMC: data pointer (ptr), function pointer (func_ptr), buffer (sized) (**)(*) Only available if your C system sports a long long type.(**) Requires 2 additional following parameters - buffer size and alignment.

Explicitly Sized Types

uint1 (also known as bit), uint4, int8, uint8, int16, uint16, int32, uint32, int64(*), and uint64(*)(*) Only available if your C system sports a 64 bit integer type.

void destroy()

Free internal offsets array.

INTVAL get_integer_keyed(PMC *k)

void set_integer_keyed(PMC *k, INTVAL x)

Get/Set an integer-type element from a struct-pointer PMC.

FLOATVAL get_number_keyed(PMC *k)

void set_number_keyed(PMC *k, FLOATVAL n)

Get/Set a float-like element from a struct-pointer PMC.

STRING *get_string keyed(PMC *k)

void set_string_keyed(PMC *k, STRING *)

Get/Set a string element from a struct-pointer PMC.

PMC *get_pmc_keyed(PMC *k)

void set_pmc_keyed(PMC *k, PMC *p)

Get/Set a PMC-like element from a struct-pointer PMC or box/unbox values from any other type of element.

INTVAL get_integer()

METHOD size()

Get the size (in bytes) required for one instance.

METHOD align()

Get the alignment (in bytes) required for an instance.

METHOD aligned_size()

Get the size of one instance plus the pad bytes to align a subsequent instance.

METHOD alloc(INTVAL n :optional)

Allocate an instance, or an array of instances when n has been provided.

METHOD array_offs(PMC *array, INTVAL n)

Return a Ptr to the nth element of an array of structs.

METHOD elt_offs(PMC *array, INTVAL n)

Return a Ptr to the nth element of a struct.

METHOD get_shape()

Obtain an integer array which describes the shape of this object.The returned array is of the same format as the one used for StructView.init_pmc.

void freeze(PMC *v)

void thaw(PMC *v)

Implement the freeze/thaw API.

Auxiliary functions

static void deallocate_ptrobj(PARROT_INTERP, PMC *obj, void *ptr)

Deallocation function to be attached to allocated instances.

static void dereference_null(PARROT_INTERP)

Throw an exception relating to attempting to derefence a NULL pointer.

static void index_out_of_bounds(PARROT_INTERP, INTVAL i)

Throw an exception about attempting to index outside the data.

static void buffer_too_small(PARROT_INTERP, size_t self_size, size_t buf_size)

Throw an exception about a buffer being too small.

static void dereference_unaligned(PARROT_INTERP, const void *base_ptr, size_t align)

Throw an exception relating to attempting to derefence an un-aligned pointer.