-*- Text -*-

Info file GSeq.nfo, hand-written by Fare 1993,1994

   This file documents the my own Generic Queue C module.
   The module, including this file should be distributed under the terms of
the GNU Public License, unless some special permission was given by the author.


File: GSeq.nfo,  Node: Top,  Up: (CLibs.nfo)

   This file documents the Generic Sequence module.

* Menu:

* Conventions::		Naming conventions relative to the module
* Implementation::	Explanation of the module's implementation
* Input::		Summary of module input
* Output::		Summary of module output

File: GSeq.nfo,  Node: Conventions,  Up: Top

   

File: GSeq.nfo,  Node: Input,  Next: Output,  Up: Top

* Menu:

* Input Defines::
* Input Functions::
* Input variables::

File: GSeq.nfo,  Node: Output,  Next: Implementation,  Up: Top

* Menu:

* Output Defines::
* Output Functions::
* Output Variables::


File: GSeq.nfo,  Node: Input Defines,					Next: Input Functions, Prev: Top,  Up: Input

*** Naming: ***
GS_NAME(x)		must prefix (postfix) x to make it a unique global
			name.
GS_PREFIX		if GS_NAME is undefined and GS_PREFIX defined,
			GS_NAME(x) will be defined by CAT(GS_PREFIX,x)

*** Parameters: ***
GS_STD_PARAMS		standard parameters to find the sequence; all GS_
			functions will use it. If no param needed, undefine it.
GS_STD_ARGS		just the name of the previous params without their
			type. Undefined if no parameter.

*** Elements: ***
GS_ELEM_TYPE		a regular type
GS_ELEM_RETURNABLE	true iff ELEM_TYPE is returnable by C.
GS_ELEM_COPY		auto-initialized by default, else procedure to copy
			an element to an element variable.
GS_ELEMENT(i)		the element referenced by index value i, assuming
			checks were successful.

*** Indices: ***
GS_INDEX_TYPE		an arithmetical, returnable type
GS_INCREMENT		pointer increment when reading
GS_POINTER		the pointer, relative to global data and/or STD_PARAMS
			of next data to read, if available.

GS_FUNCTIONS		integer (bit fields) value describing what
			functions to define.
  GSF_BASIC		Put, Get, Next
  GSF_PREV		Prev
  GSF_LIFO		Push, Pop
  GSF_FIFO		Write, Read
  GSF_PUTBACK		PutBack
  GSF_MULTIPLE		MPut, MGet, etc
  GSF_CONTROL		Reset, Flush, isEOS, isBOS, Close
  GSF_SEEK		Seek, Tell, SetIndex

*** Implementation: ***
GS_IMPLEMENTATION	Describes how the sequence is to be implemented;
			def'd iff use of:
  GSI_LINKED_LIST	a linked list
  GSI_DLINKED_LIST	a doubly linked list
  GSI_PARTIAL_BUFFER	a buffer of part of the stuff
			(list: each element is a buffer)
  GSI_RING_BUFFER	use a ring buffer
  GSI_TWO_S_POWER	a buffer size that is a power of two.
  GSI_MINUS_ARGUMENT	def'd iff negative arg is relative to bottom of stack
  GSI_IDX_POINTER	a pointer index type
  GSI_IDX_INTEGER	an integer index type
  GSI_BUFFERIZE		sequence buffers the GSO_ sequence
  GSI_UNBUFFERIZE	sequence unbuffers the GSO_ sequence
  GSI_MULTIPLE_BUF	use multiple buffers.

GSLL_LAST_IS_FIRST	for a linked list, whether the list is circular
GSLL_LAST_IS_NULL	for a linked list, whether the end is NULL

GSB_BUFGRAIN		size of the buffer grain
GSB_BUFSIZE		number of grains in a buffer
GSB_ROUND_UP		true iff size MUST be rounded to the size of the buffer
GSB_FILL		how to fill a buffer
GSB_FLUSH		how to flush it

GSMB_IS_GOOD
GSMB_FIND_FREE
GSMB_KILL_ONE
GSMB_SORTED
GSO_NAME(x)		name of the sequence to be (un)bufferized.
GSO_PREFIX		prefix for the sequence to be (un)bufferized.

**** Checking: ****

Checking result:
GS_OVERFLOW		statement to return when sequence overflowing.
GS_UNDERFLOW		statement to return when sequence underflowing.

Index Checking:
GS_IDX_CHECKING		integer (bit fields) value describing what
			sanity checks are to be done.
  GSI_PRECHECK_IDX	checking indexes before using them
  GSI_POSTCHECK_IDX	checking indexes after modifying them
GS_PTR_MAX		Maximal value for an index
GS_CHECKPTR_MIN		minimal value for an index

Value Checking:
GS_CHECK_VALUE(x)	macro to test the consistency of a GS_ELEM_TYPE value

Global checking:
GS_UNEXPECTED_VALUE	some value unexpected, used in sanity checks;
			if def'd, then PTR_MIN-1 and PTR_MAX+1 contain
			this value to test that the stack didn't overflow or
			underflow. A more elaborate test should include two
			lists of values instead. Here it is:
GS_UPPER_MAGIC		char [] containing magic data to put after the stack
GS_LOWER_MAGIC		char [] containing magic data to put before the stack



File: GSeq.nfo,  Node: Input Functions,					Next: Input Variables, Prev: Input Defines, Up: Input


File: GSeq.nfo,  Node: Input Variables,					Next: Output Defines, Prev: Input Functions, Up: Input


File: GSeq.nfo,  Node: Output Defines,					Next: Output Functions, Prev: Input Variables, Up: Output

GS_DECLARE( FUN, RET_TYPE, ARGS... ) \
			RET_TYPE GS_NAME(FUN) ( GS_STD_PARAMS, ARGS )

File: GSeq.nfo, Node: Output Functions,					Next: Output Variables, Prev: Output Defines, Up: Output

Basic functions:
- Get :		(implicit sequence) -> GS_ELEM_TYPE
- Put :		(implicit sequence), GS_ELEM_TYPE -> (implicit sequence)
- Next :	(implicit sequence) -> (implicit sequence)
- Prev :	(implicit sequence) -> (implicit sequence)
		defined iff (GSF_PREV & GS_FUNCTIONS)

LIFO Stack functions:
- Push :	x,e |-> Put(Next(x),e)
- Pop :	 	x |-> Get(x), Prev(x)

FIFO File functions:
- Write : 	x,e |-> Next(Put(x,e))
- Read :	x |-> (y |-> Get(y),y) (Next (x))
- PutBack :	x,e |-> Put(Prev(x),e)
- WriteNext :

List functions:
- Insert :

Multiple operation functions:
- MPut :
- MGet :
- MNext :
- MPrev :
- MPush :
- MPop :
- MWrite :
- MRead :
- MPutBack :
- MInsert :

Control functions:
- isBOS :
- isEOS :
- Seek :
- Reset :
- Flush :
- Close :
- DupIndex :
- Copy :

Particular objects:
- Empty :
- IsEmpty :
- IsFull :

Exceptions:
- Empty not in Image (Put), not in ReverseImage ( Sequence \ { Empty } )
- Underflow = Prev (Empty), Get (Empty)
- Sequence
- Overflow in Image (Next)

File: GSeq.nfo,  Node: Output Variables,					Next: Implementation, Prev: Output Functions, Up: Output



File: GSeq.nfo,  Node: Implementation,					Next: User Implementation, Prev: Output, Up: Top

* Menu:

* User Implementation::
* Buffering::
* Multi-Buffering::
* Ring Buffering::
* Buffer filling::
* Array::
* List::
* Double List::

File: GSeq.nfo,  Node: User implementation,				Next: Buffering, Prev: Output Variables, Up: Implementation

As it defines functions, the module defines macros to access these functions.
If the macro already exist, it won't create the function, but instead use
the macro. The macros are:

GS_ELEMENT(i)	i-th element of the sequence;	default: (*(i))
GS_NEXT(i)	index following index i; 	default: ((i)+(GS_INCREMENT))
GS_PREV(i)	index preceding index i;	default: ((i)-(GS_INCREMENT))

They all assume the validity of index i.
GS_COOK_INDEX(i)

File: GSeq.nfo,  Node: Buffering,						Next: Multi-Buffering, Prev: User Implementation, Up: Implementation

   The module assumes that the sequence is buffered, that is, that part or
whole of the sequence is placed in a contiguous memory area. This part can
be even just one element. If this is definitely not the case, you must
define the GS_ELEM(i) macro.

   To check an index against the bounds of a buffer:
GS_CHECK_BUFFER_LOWER_BOUND(i)
GS_CHECK_BUFFER_UPPER_BOUND(i)
GS_CHECK_BUFFER_BOUNDS(i)

   The checks will produce GS_BUFFER_UNDERFLOW and GS_BUFFER_OVERFLOW
respectively. They can be preset by the user. If the GSI_BUFFER_IS_ALL
option is set, these will be redirected to GS_CHECK_LOWER_BOUND,
GS_CHECK_UPPER_BOUND, and GS_CHECK_BOUNDS.
File: GSeq.nfo,  Node: Multi-Buffering,						Next: Ring Buffering, Prev: Buffering, Up: Implementation

   With Multi-Buffering on, the module assumes there are several buffers for
the same sequence, but no buffer overlap.
   The various primitives will then use some user-defined macros to access
the multiple buffers. The GSI_FIXED_MBUF, and GSI_1_BUF_PER_IDX specialize even
further the implementation; actually, even the default options predefines the
primitives for only one buffer.


File: GSeq.nfo,  Node: Ring Buffering,					Next: Buffer filling, Prev: Multi-Buffering, Up: Implementation


File: GSeq.nfo,  Node: Buffer filling,					Next: Array, Prev: Ring Buffering, Up: Implementation


File: GSeq.nfo,  Node: Array,						Next: List, Prev: Buffer filling, Up: Implementation


File: GSeq.nfo,  Node: List,						Next: Double List, Prev: Array, Up: Implementation


File: GSeq.nfo,  Node: Double List,					Prev: List, Up: Implementation

