Documentation from flex.h

Introduction	[top]

ROV - Easy applications from C

Copyright - © Jason Tribbeck / 7th ARM 1994-2001

Contributing authors - Jason Tribbeck

File - flex.h

Type - subsystem

Description

The flex subsystem is a flexible memory allocation scheme, modelled very closely on Acorn's flex flexible memory allocation scheme.

It relies on maintaining a list of memory anchors that are held in normal memory that are automatically updated whenever memory is rearranged (during a resize and a deallocation). These anchors form pointers to blocks of memory held in the flex memory system.

If no memory rearrangement is occurring, then pointers to memory within flex blocks is permitted, but if memory rearrangement occurs, these pointers will have to be recalculated based on the anchor pointers. In general, it is easier to use offsets from anchors instead of pointers based on anchors. See the flex tutorial for more details.

If the non-dynamic area version is used, the normal r-versions of memory allocations have to be replaced so that they use the first flex memory block (whose base address never changes). This is normally by the newmalloc() functions.

See also: main.h

flex_ptr (type definition)	[top]

Definition of a flex anchor pointer.

typedef void **flex_ptr;

flex_reg (function pointer)	[top]

Definition of a flex event handler.

Parameters:

 - int type - the notification type

typedef void (*flex_reg)(int type);

See also: FLEX_ALLOC, FLEX_CLEAR, FLEX_FREE, FLEX_MOVE, FLEX_POSTRESIZE, FLEX_PRERESIZE, FLEX_RESIZE, FLEX_SWAP, FLEX_USER

flex_init	[top]

Initialises the flex memory system.

void flex_init(void);

See also: flex_initdyn()

flex_initdyn	[top]

Initialises the flex memory system using dynamic areas.

void flex_initdyn(void);

See also: flex_init(), flex_limitdyn()

flex_limitdyn	[top]

Limit the amount of dynamic area to use

Parameters:

 - int size - the size to limit the dynamic area to.

Note - This must be called before calling flex_initdyn().

void flex_limitdyn(int size);

See also: flex_initdyn();

flex_alloc	[top]

Allocate a memory block.

Parameters:

 - flex_ptr anchor - the pointer to the flex anchor.
 - int size - the size to allocate.

Returns:

 -  non-zero for success.

Note - The flex anchor must exist outside of the flex memory area.

int flex_alloc(flex_ptr anchor,
	       int size);

See also: flex_allocmax(), flex_realloc()

flex_allocmax	[top]

Allocate the most available.

Parameters:

 - flex_ptr anchor - the pointer to the flex anchor.

Returns:

 -  non-zero for success.

Note - The flex anchor must exist outside of the flex memory area.

int flex_allocmax(flex_ptr anchor);

See also: flex_alloc()

flex_realloc	[top]

Resize or allocate a flex block

Parameters:

 - flex_ptr anchor - the flex anchor.
 - int size - the new size.

Returns:

 -  non-zero for success.

Note - If the anchor points to NULL, then it is equivalent of calling flex_alloc(). If it is not null, then it is equivalent of calling flex_extend(). If the size is 0, then it is freed.

int flex_realloc(flex_ptr anchor,
		 int size);

See also: flex_alloc(), flex_extend(), flex_free()

flex_free	[top]

Frees a flex block

Parameters:

 - flex_ptr anchor - the flex anchor.

Note - The anchor will point to NULL after this call.

void flex_free(flex_ptr anchor);

flex_extend	[top]

Resize an existing flex block.

Parameters:

 - flex_ptr anchor - the flex anchor.
 - int size - the new size.

Returns:

 -  non-zero for succes.

Note - If the size is zero, then the anchor is freed.

int flex_extend(flex_ptr anchor,
		int size);

See also: flex_extendby(), flex_realloc()

flex_extendby	[top]

Resize an existing flex block relatively.

Parameters:

 - flex_ptr anchor - the flex anchor.
 - int extension - the size to extend (or contract) by.

Returns:

 -  non-zero for success.

Note - If the size becomes less than zero, then the anchor is freed.

int flex_extendby(flex_ptr anchor,
		  int extension);

See also: flex_extend()

flex_register	[top]

Register a flex event handler

Parameters:

 - flex_reg handler - the flex event handler function.

Note - There can be only one flex event handler registered.

void flex_register(flex_reg handler);

flex_clear	[top]

Clears all flex allocations

Note - all anchors will point to NULL.

void flex_clear(void);

flex_max	[top]

Get the maximum allocation size.

Returns:

 -  the maximum allocation size.

Note - This will include the WIMP's free space.

int flex_max(void);

flex_callregister	[top]

Call the registered flex event handler.

Parameters:

 - int event - the event code.

void flex_callregister(int event);

flex_size	[top]

Get the size of a flex block.

Parameters:

 - flex_ptr anchor - the flex anchor.

Returns:

 -  the size of the allocated memory for that anchor.

int flex_size(flex_ptr anchor);

flex_swap	[top]

Swap two anchors over.

Parameters:

 - flex_ptr anchor1 - the first anchor.
 - flex_ptr anchor2 - the second anchor.

Note - This can be seen as swapping the memory contents over, but is actually swapping the pointers (and therefore very much faster).

void flex_swap(flex_ptr anchor1,
	       flex_ptr anchor2);

flex_move	[top]

Moves one flex pointer to another.

Parameters:

 - flex_ptr anchor1 - the source anchor.
 - flex_ptr anchor2 - the destination anchor.

Note - This is effectively transferring memory from one anchor to another.

Note - If anchor2 points to existing data, then it is freed first.

void flex_move(flex_ptr anchor1,
	       flex_ptr anchor2);

flex_usingdynamic	[top]

Find out if flex is using dynamic areas.

Returns:

 -  non-zero if a dynamic area is being used.

int flex_usingdynamic(void);

FLEX_PRERESIZE (definition)	[top]

Event code passed to flex event handler just before a resize of memory is to take place.

#define FLEX_PRERESIZE  (-1)

FLEX_POSTRESIZE (definition)	[top]

Event code passed to flex event handler just after a resize of memory has taken place.

#define FLEX_POSTRESIZE (-2)

FLEX_ALLOC (definition)	[top]

Event code passed to flex event handler when a successful allocation is about to return back to main application code.

#define FLEX_ALLOC      (0)

FLEX_FREE (definition)	[top]

Event code passed to flex event handler when a successful free call is about to return back to main application code.

#define FLEX_FREE       (1)

FLEX_RESIZE (definition)	[top]

Event code passed to flex event handler when a successful resize call is about to return back to main application code.

#define FLEX_RESIZE     (2)

FLEX_CLEAR (definition)	[top]

Event code passed to flex event handler when a successful clear call is about to return back to main application code.

#define FLEX_CLEAR      (3)

FLEX_SWAP (definition)	[top]

Event code passed to flex event handler when a successful swap call is about to return back to main application code.

#define FLEX_SWAP       (4)

FLEX_MOVE (definition)	[top]

Event code passed to flex event handler when a successful move call is about to return back to main application code.

#define FLEX_MOVE       (5)

FLEX_USER (definition)	[top]

Event code base number for application events to pass into flex event handler.

#define FLEX_USER       (100)

Generated Thu Feb 7 23:22:51 2002