XCLE_Obj

XCLE: eXtensible Concatenative Language Engine
Copyright (C) 2000-2006 Yann LANDRIN-SCHWEITZER a.k.a. Varkhan

This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Author: Yann LANDRIN-SCHWEITZER
Contact: varkhan@varkhan.net
Homepage: http://www.varkhan.net/

XCLE_Code memory management

Function XCLE_CodeAlloc

XCLE_Code XCLE_CodeAlloc(void) ;
Allocates a new Code object, with no execution handler nor data section.

Returns:
	_ NULL	: if no memory was available
	else a new Code object.

Errors:
	_ EINVAL	: if a NULL was passed as argument
	_ ENOMEM	: if no memory was available

	Note:
		This constructor is only there as a utility, for the returned code object is totally
		useless: it has no name, no stack expectaion, no execution handler, and its data
		section is undefined. Using it would only result in a place filler, and executing
		it would do nothing.

Function XCLE_CodeCopy

XCLE_Code XCLE_CodeCopy(XCLE_Code cod) ;
Copies a Code object, along with its data segment.

	Args:
		_ cod	: Code object to copy

Returns:
	_ NULL	: if a NULL Code was passed as argument or no memory was available
	else a complete copy of the original Code object.

Errors:
	_ EINVAL	: if a NULL Code was passed as argument
	_ ENOMEM	: if no memory was available

	Note:
		This is a complete copy: the Code's data segment is also replicated.

Function XCLE_CodeClone

XCLE_Code XCLE_CodeClone(XCLE_Code cod) ;
Clones a Code object.

	Args:
		_ cod	: Code object to clone

Returns:
	_ NULL	: if a NULL Code was passed as argument or no memory was available
	else a simple copy of the Code object.

Errors:
	_ EINVAL	: if a NULL Code was passed as argument
	_ ENOMEM	: if no memory was available

	Note:
		This is a partial copy: the Code's data segment is the same as the original's.

Function XCLE_CodeUpRef

XCLE_Code XCLE_CodeDup(XCLE_Code cod) ;
Increases the reference count of a Code object and of its data segment.

	Args:
		_ cod	: Code to reference

Returns:
	_ NULL	: if a NULL Code was passed as argument
	else the referenced Code object.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

Function XCLE_CodeDnRef

XCLE_Code XCLE_CodeDnRef(XCLE_Code cod) ;
Decreases the reference count of a Code object and of its data segment.

	Args:
		_ cod	: Code to dereference

Returns:
	_ NULL	: if a NULL Code was passed as argument
	else the dereferenced Code object.

Errors:
	_ EINVAL	: if a NULL Code was passed as argument
	_ ENOMEM	: if no memory was available

Function XCLE_CodeFree

void XCLE_CodeFree(XCLE_Code cod) ;
Frees a Code object.

	Args:
		_ cod	: Code to free

XCLE_Code name, handler, and data

Function XCLE_CodeGetName

char * XCLE_CodeGetName(XCLE_Code cod) ;
Returns the name field of a Code object.

	Args:
		_ cod	: Code to query

Returns:
	_ NULL	: if a NULL Code was passed as argument, or no memory was available
	else the name of this Code, as a \0-terminated string.

Errors:
	_ EINVAL	: if a NULL Code was passed as argument
	_ ENOMEM	: if no memory was available

	Note:
		The returned char * buffer is allocated dynamically, with malloc. It is the
		responsibility of the programmer to free it when it is not used anymore.

Function XCLE_CodeSetName

XCLE_Code XCLE_CodeSetName(XCLE_Code cod, char * name) ;
Updates the name field of a Code objetc.

Args:
	_ cod	: Code to update
	_ name	: the new name (\0-terminated string)

Returns:
	_ NULL	: if a NULL Code was passed as argument, or no memory was available
	else the original 'cod' object.

Errors:
	_ EINVAL	: if a NULL Code was passed as argument
	_ ENOMEM	: if no memory was available

Function XCLE_CodeGetHandler

void * XCLE_CodeGetHandler(XCLE_Code cod) ;
Returns a pointer to the execution handler of a Code object.

	Args:
		_ cod	: Code to query

Returns:
	_ NULL	: if a NULL Code was passed as argument
	else the pointer to the execution handler.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

	Note:
		If you do not know what is the Code's execution handler, avoid this function.
		For instruction set programmers: this is the same address as the 'func' member
		in the CodeDef structure, that is, a CodeOperator function pointer.

Function XCLE_CodeSetHandler

XCLE_Code XCLE_CodeSetHandler(XCLE_Code cod, void * func) ;
Sets the execution handler of a Code object.

Args:
	_ cod	: Code to update
	_ func	: the new execution handler

Returns:
	_ NULL	: if a NULL Code was passed as argument
	else the original 'cod' object.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

	Note:
		If you do not know what is the Code's execution handler, avoid this function.
		For instruction set programmers: execution handlers are generally set through
		the parsing routines, that will look up a CodeDef structure from declared tables
		and set execution handlers accordingly. Setting it by hand should be done with care.

Function XCLE_CodeGetData

XCLE_Object XCLE_CodeGetData(XCLE_Code cod) ;
Returns the data segment of a Code object.

	Args:
		_ cod	: Code to query

Returns:
	_ NULL	: if a NULL Code was passed as argument
	else the data segment.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

	Note:
		If you do not know what is the Code's data segment, avoid this function.
		For instruction set programmers: instructions have generally empty (NULL)
		data segment. These are only used for parametrable instructions.

Function XCLE_CodeSetData

XCLE_Code XCLE_CodeSetData(XCLE_Code cod, XCLE_Object data) ;
Sets the data segment of a Code object.

Args:
	_ cod	: Code to update
	_ data	: data segment

Returns:
	_ NULL	: if a NULL Code was passed as argument
	else the original 'cod' objetc.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

	Note:
		If you do not know what is the Code's data segment, avoid this function.
		For instruction set programmers: you will probably let the users determines
		data segments for parametrable instructions dynamically, through the parsing
		routines. However, executing a checking pass on data segments before execution
		can be useful. Combine the GetData and SetData methods with recursive ListMap
		calls to provide a data segment verification pass.

XCLE_Code signature and prototypes

Function XCLE_CodeSignatureNum

unsigned short XCLE_CodeSignatureNum(XCLE_Code cod) ;
Returns the number of distinct signatures for this Code.

	Args:
		_ cod	: Code to query

Returns:
	_ -1	: if a NULL Code was passed as argument
	else the number of distinct signatures.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

	Note:
		A Code's signature is a set of expected arguments number/types, and the corresponding
		returned object number/types. Several can exist for a single Code, covering different
		instruction semantics. This function only counts the number of such semantics.

Function XCLE_CodeSignatureArgc

unsigned short XCLE_CodeSignatureArgc(XCLE_Code cod, unsigned short sign) ;
Returns the number of arguments required for a particular signature.

Args:
	_ cod	: Code to query
	_ sign	: index of signature

Returns:
	_ -1	: if a NULL Code was passed as argument
	else the number of arguments required for the signature of index 'sign'.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument, or the signature index was invalid

	Note:
		A Code's signature is a set of expected arguments number/types, and the corresponding
		returned object number/types. Several can exist for a single Code, covering different
		instruction semantics. This function will return the number of arguments expected for
		the designated set.

Function XCLE_CodeSignatureRetc

unsigned short XCLE_CodeSignatureRetc(XCLE_Code cod, unsigned short sign) ;
Returns the number of results returned for a particular signature.

Args:
	_ cod	: Code to query
	_ sign	: index of signature

Returns:
	_ -1	: if a NULL Code was passed as argument
	else the number of results returned for the signature of index 'sign'.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument, or the signature index was invalid

	Note:
		A Code's signature is a set of expected arguments number/types, and the corresponding
		returned object number/types. Several can exist for a single Code, covering different
		instruction semantics. This function will return the number of results returned for
		the designated set.

Function XCLE_CodeSignatureMatch

unsigned short XCLE_CodeSignatureMatch(XCLE_Code cod, unsigned short argc, XCLE_Type * argt, unsigned short retc, XCLE_Type * rett) ;
Returns the number of signature matches for a given set of argument types and expected results.

Args:
	_ cod	: Code to query
	_ argc	: number of arguments
	_ argt	: argument types (this is an XCLE_Type[argc] vector)
	_ retc	: number of expected returns
	_ rett	: types of expected returns (this is an XCLE_Type[retc] vector)

Returns:
	_ -1	: if a NULL Code was passed as argument
	else the number of signature matches.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

	Note:
		This function computes the number of execution semantics supported by the Code object
		and consistent with the given argument types and expected returns. In most cases,
		nothing is expected of returned values, so setting 'retc' to 0 and 'rett' to NULL is
		appropriate.

Function XCLE_CodeSignatureAdd

XCLE_Code XCLE_CodeSignatureAdd(XCLE_Code cod, unsigned short argc, XCLE_Type * argt, unsigned short retc, XCLE_Type * rett) ;
Adds a new accepted signature for a Code object.

Args:
	_ cod	: the Code to update
	_ argc	: number of arguments
	_ argt	: argument types (this is an XCLE_Type[argc] vector)
	_ retc	: number of returns
	_ rett	: returns types (this is an XCLE_Type[retc] vector)

Returns:
	_ NULL	: if a NULL Code was passed as argument or an error occured
	else the updated 'cod' object.

Errors:
	_ ENOMEM	: if a reallocation failed
	_ EINVAL	: if a NULL Code was passed as argument

	Note:
		A newly allocated Code object has no registered signature (XCLE_CodeSignatureNum would
		return 0). This is the method to be used to set the signature(s) before profiling or
		execution of objects using this Code.

Function XCLE_CodeSignatureDel

XCLE_Code XCLE_CodeSignatureDel(XCLE_Code cod, unsigned short argc, XCLE_Type * argt, unsigned short retc, XCLE_Type * rett) ;
Deletes a signature from a Code object.

Args:
	_ cod	: the Code to update
	_ argc	: number of arguments
	_ argt	: argument types (this is an XCLE_Type[argc] vector)
	_ retc	: number of returns
	_ rett	: returns types (this is an XCLE_Type[retc] vector)

Returns:
	_ NULL	: if a NULL Code was passed as argument
	else the updated 'cod' object.

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

	Note:
		This method is provided for the sake of complteness, as deleting code signatures has
		no real use. The 'argc', 'argt', 'retc' and 'rett' must have the same values as those
		passed to XCLE_CodeSignatureAdd to add the targeted signature.

XCLE_Code object conversion and comparison

Function XCLE_ObjectToCode

XCLE_Code XCLE_ObjectToCode(XCLE_Object obj) ;
Converts a generic object into a Code object, if possible.

	Args:
		_ obj	: Object to convert

Returns:
	_ NULL	: if a NULL object, or one with incompatible types, was passed as argument
	else the actual Code object embedded into 'obj'.

	Errors:
		_ EINVAL	: if a NULL or invalid object was passed as argument

Function XCLE_CodeEqual

unsigned char XCLE_CodeEqual(XCLE_Code cod, XCLE_Code codw) ;
Compares two Code objects.

Args:
	_ cod	: Code to compare
	_ codw	: reference Code

Returns:
	_ -1	: if a NULL Code was passed as argument
	_ 0	: if the two Codes were distinct
	_ +1	: if the two Codes had the same name, argument and return expectations, and data segment

	Errors:
		_ EINVAL	: if a NULL Code was passed as argument

Generated by textdoc2html - 2006-02-22