Home · Pages · Index · Overviews

Mylib Core Module Reference

System-wide types and routines. More...

 #include <mylib.h>

Structures

  Value : union
uval : uint64
ival : int64
rval : float64
Holds uint8, uint16, uint32, and uint64 values
Holds int8, int16, int32, and int64 values
Holds float32 and float64 values

Enumerated Scalars

  Value_Kind : { UVAL, IVAL, FVAL }
  Value_Type : { UINT8_TYPE, UINT16_TYPE, UINT32_TYPE, UINT64_TYPE,
    INT8_TYPE, INT16_TYPE, INT32_TYPE, INT64_TYPE,
    FLOAT32_TYPE, FLOAT64_TYPE }
 
 
 
  Operator : { SET_OP, ADD_OP, SUB_OP, MUL_OP, DIV_OP, POW_OP, LSH_OP, RSH_OP, MIN_OP, MAX_OP }
  Comparator : { LE_COMP, LT_COMP, EQ_COMP, NE_COMP, GT_COMP, GE_COMP }
 
 

Descriptive Types

  uint8 : unsigned char
  uint16 : unsigned short
  uint32 : unsigned int
  uint64 : unsigned long long
  int8 : signed char
  int16 : signed short
  int32 : signed int
  int64 : signed long long
  float32 : float
  float64 : double
An 8-bit unsigned integer
A 16-bit unsigned integer
A 32-bit unsigned integer
A 64-bit unsigned integer
An 8-bit signed integer
A 16-bit signed integer
A 32-bit signed integer
A 64-bit signed integer
A 32-bit floating point number
A 64-bit floating point number
 
  string : char *
  boolean : int
  tristate : int
A pointer to a '\0'-terminated sequence of char's
0 denotes false and not-0 denotes true
< 0 denotes less, 0 denotes equal, and > denotes greater
 
  Dimn_Type : int32
  Indx_Type : int64
  Size_Type : int64
  Offs_Type : int64
Type of an array dimension
Type of an index into the data space of an array
Type of the size of an array
Type of an offset from an index in an array

Macro Constants

  NUM_THREADS = 8
# of simultaneous executing threads supported
 
  DIMN_TYPE = INT32_TYPE
  INDX_TYPE = INT64_TYPE
  SIZE_TYPE = INT64_TYPE
  OFFS_TYPE = INT64_TYPE
Value_Type of a Dimn_Type
Value_Type of an Indx_Type
Value_Type of a Size_Type
Value_Type of an Offs_Type
 
  DIMN_SCALE = 32
  INDX_SCALE = 64
  SIZE_SCALE = 64
  OFFS_SCALE = 64
Array.scale of a Dimn_Type
Array.scale of an Indx_Type
Array.scale of a Size_Type
Array.scale of an Offs_Type

Routines

Value VALU (uint64 u)
Value VALI (int64 i)
Value VALF (float64 f)

void Use_Zero_Boundary ()
void Use_Reflective_Boundary ()
void Use_Wrap_Boundary ()
void Use_Extend_Boundary ()
void Use_Inversion_Boundary ()

Detailed Description

The Mylib module contains types, constants, enumerated scalars, and routines, that are used throughout the system and are not properly a part of any class or module per se.

A number of type definitions are used throughout mainly because they further document the meaning of a return value or parameter. For example, a boolean is just an int, but when an entity is declared to be of type boolean one immediately understands that it is only conveying true or false according to whether its value is non-zero or not, respectively. Similarly, a string is always a C-style 0-terminated sequence of chars.

We carefully adhere to using such descriptive types for variables pertaining to arrays. Specifically: Dimn_Type is used consistently for the type of an array's dimension, Indx_Type for an index into an array, Size_Type for the size of an array, and Offs_Type for an offset relative to an index in an array. Note carefully that a dimension is limited to 2 billion but the size of an array is effectively unbounded. Moreover, by choosing signed versus unsigned integers for these types, while we lose the ability to have dimensions up to 4 billion, the potential for subtle signed-unsigned value comparison bugs and other such complications are avoided, easing programming for both implementors and users alike. In addition there are also macro defined constants for the Value_Type and scale of each of these four array location types as it is not uncommon for one to make arrays of them, e.g. a Coordinate is a Vector of dimension values.

Many routines operate on an Array where the array may have any dimensionality and its elements can be of any type. Similarly, many routines need to recieve or return a Value that is a single number that may be of any of the ten scalar types over which an array may be defined. The enum Value_Type captures the ten possible types and a Value is realized as a union that can hold any Value_Type as either a uint64, an int64, or a float64. The enum Value_Kind indicates whether a Value_Type should be interpreted as a uint64 (i.e. UVAL), an int64 (i.e. IVAL), or a float64 (i.e. FVAL). The 3-routines VALU, VALI, and VALF are used to easily create values, e.g.

 VALF(2.3)
 VALI(2*i+3)

where in the example i is an integer variable. The important feature of a Value is that its size is 8-bytes and so it is passed and returned exactly as C base type, say a double, would be. On some machines the routines are realized as macros.

Routines in Mylib often need the concept of border values beyond the boundary of the array. Matlab makes you create another array that explicitly has the required border. This is exceedingly wasteful in memory, especially when one is working on a very large 3D or 4D array, a common occurence with microscopy data. Mylib currently supports five types of boundaries that are implicit in that any library routine that needs values beyond the border of the array computes them on the fly. For users, that need to write code that involves boundary effects, the library simplifes matters with a Frame object that allows one to get these border values explicity in a small window of current interest as one traverses the array in question.

The current boundary effect is set globally for the system by calling one of five boundary routines that sets the implicit boundary type according to the name of the routine. Initially the "0-boundary" is the current boundary effect. A given boundary effect stays in force until it is changed with another such call. Note that this is not re-entrant albeit it is thread-safe. The five boundary setting routines and the definition of their boundaries are given in the table below. To keep it conceptually simple it is assumed A[0..W] is a one-dimensional array and the table shows how the value of A[-x] and A[W+x] is computed for x > 0. One can extrapolate a boundary effect to higher dimensions by induction.

FunctionBoundary Effect                 
Use_Zero_Boundary A[-x] = 0A[W+x] = 0
Use_Reflective_Boundary A[-x] = A[x]A[W+x] = A[w-x]
Use_Wrap_Boundary A[-x] = A[W-x]A[W+x] = A[x]
Use_Extend_Boundary A[-x] = A[0]A[W+x] = A[W]
Use_Inversion_Boundary A[-x] = 2*A[0]-A[x]A[W+x] = 2*A[W]-A[W-x]


Structure Documentation

Value : union
uval: uint64
ival: int64
rval: float64

A Value is a union that holds either a uint64, int64, or float64 and is thus capable of encoding any value over the ten possible types for array elements. The appealing property of a Value is that it behaves like an 8-byte scalar, e.g. a double, and so is passed by value, can be returned by a function, and so on. The routines VALU, VALI, and VALF create values for you.


Enumerated Scalars Documentation

Value_Kind: { UVAL, IVAL, FVAL }

The three possible cases for the union of a Value. UVAL indicates a value holds a uint64 value, IVAL indicates an int64 value, and FVAL indicates a float64 value.

Value_Type: { UINT8_TYPE, UINT16_TYPE, UINT32_TYPE, UINT64_TYPE,
    INT8_TYPE, INT16_TYPE, INT32_TYPE, INT64_TYPE,
    FLOAT32_TYPE, FLOAT64_TYPE }

The ten possible types of elements for an array. The interpretation of each enum constant should be obvious, e.g. UINT32_TYPE denotes that the elements are of type uint32.

Operator: { SET_OP, ADD_OP, SUB_OP, MUL_OP, DIV_OP, POW_OP, LSH_OP, RSH_OP, MIN_OP, MAX_OP }

An Operator value specifies that a particular binary operation is to be applied. For examples, see Array_Op_Scalar and Array_Op_Array. The values and associated operations are as follows:

OperatorEffect
SET_OP a = b
ADD_OP a + b
SUB_OP a - b
MUL_OP a * b
DIV_OP a / b
POW_OP a ^ b
LSH_OP a << b
RSH_OP a >> b
MIN_OP min(a,b)
MAX_OP max(a,b)

Comparator: { LE_COMP, LT_COMP, EQ_COMP, NE_COMP, GT_COMP, GE_COMP }

A Comparator value specifies that a particular comparison is to be performed. For examples, see Draw_Floodfill and Record_Basic. The values and associated comparisons are as follows:

OperatorEffect
LE_COMP a <= b
LT_COMP a < b
EQ_COMP a = b
NE_COMP a != b
GT_COMP a > b
GE_COMP a >= b


Descriptive Types Documentation

Dimn_Type: int32
Indx_Type: int64
Size_Type: int64
Offs_Type: int64

Dimn_Type denotes the type of a dimension of an array, Indx_Type the type of an index into an array, Size_Type the size of an array, and Offs_Type an offset relative to an index into an array. Note carefully that a dimension is limited to 2 billion but the size of an array is effectively unbounded. Moreover, by choosing signed versus unsigned integers for these types, while we lose the ability to have dimensions up to 4 billion, the potential for subtle signed-unsigned value comparison bugs and other such complications are avoided, easing programming for both implementors and users alike.


Macro Constants Documentation

NUM_THREADS= 8

In order to be thread safe, Mylib routines involve critical sections when a common resource must be shared amongst threads. In order to allow for parallelism, Mylib often maintains NUM_THREADS instances of the resource and lets up to that many threads proceed through their critical sections in parallel, each with a different instance of the resource. As such NUM_THREADS is a critical determiner of threaded code performance and ideally it should be equal to the number of hardware cores of the underlying machine. In the current package it is set to 8. If you decide to tune this parameter, you must rebuild the system after redefining it.


Routine Documentation

Value VALU (uint64 u)
Value VALI (int64 i)
Value VALF (float64 f)

These simple functions create Values of each possible Value_Kind. On compilers that support it, they are realized as macros.

void Use_Zero_Boundary ()

Set the current boundary effect to the "zero-border", i.e., A[-x] = A[W+x] = 0 for x > 0 and A[0..W] a one-dimensional array. The image below illustrates this border for a 2-dimensional array delimited by the white rectangle, with the border elements in green.

void Use_Reflective_Boundary ()

Set the current boundary effect to the "reflective-border", i.e., A[-x] = A[x] and A[W+x] = A[W-x] for x > 0 and A[0..W] a one-dimensional array. The image below illustrates this border for a 2-dimensional array delimited by the white rectangle, with the border elements in green.

void Use_Wrap_Boundary ()

Set the current boundary effect to the "wrap-border", i.e., A[-x] = A[W-x] and A[W+x] = A[x] for x > 0 and A[0..W] a one-dimensional array. The image below illustrates this border for a 2-dimensional array delimited by the white rectangle, with the border elements in green.

void Use_Extend_Boundary ()

Set the current boundary effect to the "extend-border", i.e., A[-x] = A[0] and A[W+x] = A[W] for x > 0 and A[0..W] a one-dimensional array. The image below illustrates this border for a 2-dimensional array delimited by the white rectangle, with the border elements in green.

void Use_Inversion_Boundary ()

Set the current boundary effect to the "inversion-border", i.e., A[-x] = 2*A[0]-A[x] and A[W+x] = 2*A[W]-A[W-x] for x > 0 and A[0..W] a one-dimensional array. The image below illustrates this border for a 2-dimensional array delimited by the white rectangle, with the border elements in green.