Embedded/common/src/b_BasicEm/Context.h - platform/external/neven - Git at Google

 /*
  * Copyright (C) 2008 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #ifndef bbs_CONTEXT_EM_H
 #define bbs_CONTEXT_EM_H

 /* ---- includes ----------------------------------------------------------- */

 #include "b_BasicEm/Basic.h"
 #include "b_BasicEm/MemTbl.h"
 #include "b_BasicEm/DynMemManager.h"

 /* ---- related objects  --------------------------------------------------- */

 struct bbs_Context;

 /* ---- typedefs ----------------------------------------------------------- */

 /** error handler function pointer */
 typedef void ( *bbs_errorFPtr )( struct bbs_Context* cpA );

 /** callback handler function pointer */
 typedef uint32 ( *bbs_callbackFPtr )( struct bbs_Context* cpA );

 /* ---- constants ---------------------------------------------------------- */

 #define bbs_CONTEXT_MAX_ERRORS			8
 #define bbs_CONTEXT_MAX_MEM_MANAGERS	8

 #ifdef bbs_COMPACT_MESSAGE_HANDLING
 /* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
 #define bbs_ERROR_MAX_FILE_CHARS	24
 /* characters allocated for text message (minimum 1) */
 #define bbs_ERROR_MAX_TEXT_CHARS	1
 #else
 /* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
 #define bbs_ERROR_MAX_FILE_CHARS	52
 /* characters allocated for text message (minimum 1) */
 #define bbs_ERROR_MAX_TEXT_CHARS	256
 #endif

 /* defined error codes */
 #define bbs_ERR_OK						0	/* no error condition */
 #define bbs_ERR_ERROR					1	/* generic error */
 #define bbs_ERR_OUT_OF_MEMORY			2	/* malloc handler returns with NULL*/
 #define bbs_ERR_MEMORY_OVERFLOW			3	/* not enough memory in a segment or no segment */
 #define bbs_ERR_WRONG_VERSION			4	/* incompatible version in ..._memRead() */
 #define bbs_ERR_CORRUPT_DATA			5	/* corrupt data in ..._memRead()*/
 #define bbs_ERR_CALLBACK_ERROR			6	/* a defined error originiating from a callback function */

 /* ---- object definition -------------------------------------------------- */

 /** error object */
 struct bbs_Error
 {
 	/* error code */
 	uint32 errorE;

 	/* line number */
 	uint32 lineE;

 	/* file name */
 	char fileE[ bbs_ERROR_MAX_FILE_CHARS ];

 	/* error text */
 	char textE[ bbs_ERROR_MAX_TEXT_CHARS ];
 };

 /* ------------------------------------------------------------------------- */

 /** context object */
 struct bbs_Context
 {

 	/* ---- private data --------------------------------------------------- */

 	/** error stack */
 	struct bbs_Error errStackE[ bbs_CONTEXT_MAX_ERRORS ];

 	/** error stack index */
 	uint32 errIndexE;

 	/** memory table */
 	struct bbs_MemTbl memTblE;

 	/** multiple purpose dynamic memory managers */
 	struct bbs_DynMemManager dynMemManagerArrE[ bbs_CONTEXT_MAX_MEM_MANAGERS ];

 	/** number of used memory managers */
 	uint32 dynMemManagerArrSizeE;

 	/** error function handler */
 	bbs_errorFPtr errorHandlerE;

 	/** callback function handler */
 	bbs_callbackFPtr callbackHandlerE;

 	/** user-defined pointer */
 	void* userPtrE;

 	/* ---- public data ---------------------------------------------------- */

 };

 /* ---- associated objects ------------------------------------------------- */

 /* ---- external functions ------------------------------------------------- */

 /* ---- \ghd{ constructor/destructor } ------------------------------------- */

 /** initializes bbs_Context  */
 void bbs_Context_init( struct bbs_Context* cpA );

 /** frees bbs_Context  */
 void bbs_Context_exit( struct bbs_Context* cpA );

 /* ---- \ghd{ operators } -------------------------------------------------- */

 /** copy operator */
 void bbs_Context_copy( struct bbs_Context* cpA, const struct bbs_Context* srcPtrA );

 /* ---- \ghd{ query functions } -------------------------------------------- */

 /* ---- \ghd{ modify functions } ------------------------------------------- */

 /** composes an error object */
 struct bbs_Error bbs_Error_create( uint32 errorA, uint32 lineA, const char* fileA, const char* textA, ... );

 /* ---- \ghd{ memory I/O } ------------------------------------------------- */

 /* ---- \ghd{ exec functions } --------------------------------------------- */

 /****** ERROR HANDLING *********/

 /** puts an error onto the error stack (returns false if stack was already full) */
 flag bbs_Context_pushError( struct bbs_Context* cpA, struct bbs_Error errorA );

 /** takes the last error from stack and returns it (when stack is empty: returns the error at stack position 0)*/
 struct bbs_Error bbs_Context_popError( struct bbs_Context* cpA );

 /** returns the last error of stack without removing it (when stack is empty: returns the error at stack position 0)*/
 struct bbs_Error bbs_Context_peekError( struct bbs_Context* cpA );

 /** returns true if the error stack is not empty */
 flag bbs_Context_error( struct bbs_Context* cpA );

 /** sets error handler; returns pointer to previous error handler
  *  Pointer to Error handler can be NULL (->no handler call)
  *  The error handler is called by function pushError diectly after an error was posted
  */
 bbs_errorFPtr bbs_Context_setErrorHandler( struct bbs_Context* cpA,
 									       bbs_errorFPtr errorHandlerA );

 /*******************************/

 /****** CALLBACK HANDLING ******/

 /** call the callback handler, push error if return value is != bbs_ERR_OK */
 void bbs_Context_doCallback( struct bbs_Context* cpA );

 /** sets callback handler; returns pointer to previous callback handler
  *  Pointer to callback handler can be NULL (->no handler call)
  *  The callback handler is called by function doCallback
  */
 bbs_callbackFPtr bbs_Context_setCallbackHandler( struct bbs_Context* cpA,
 									             bbs_callbackFPtr callbackHandlerA );

 /*******************************/

 /******* MEMORY HANDLING *******/

 /** adds a static memory segment to memory table of context */
 void bbs_Context_addStaticSeg(	struct bbs_Context* cpA,
 							    uint16* memPtrA, /* pointer to memory (32bit aligned)*/
 								uint32 sizeA,    /* size of memory segment in 16 bit units */
 								flag sharedA,    /* Indicates that this segment is to be shared among multiple objects */
 								uint32 idA );    /* ID of segment, id=0: unspecified */

 /* adds a dynamic memory segment to memory table of context
  * Upon destruction of the context object any residual will be freed automatically
  */
 void bbs_Context_addDynamicSeg(	struct bbs_Context* cpA,
 								bbs_mallocFPtr mallocFPtrA,	/* function pointer to external mem alloc function (s. comment of type declaration)*/
 								bbs_freeFPtr freeFPtrA,     /* function pointer to external mem free function */
 								flag sharedA,    /* Indicates that this segment is to be shared among multiple objects */
 								uint32 idA );    /* ID of segment, id=0: unspecified */


 /** Returns allocated memory in selected exclusive segment in units of 16bits */
 uint32 bbs_Context_exclAllocSize( struct bbs_Context* cpA, uint32 segIndexA );

 /** Returns allocated memory in selected exclusive segment in units of 16bits
  *  Note that in case of static memory the return value might not reflect
  *  the actually allocated memory amount.
  */
 uint32 bbs_Context_shrdAllocSize( struct bbs_Context* cpA, uint32 segIndexA );

 /*******************************/


 /** quick compact setup for dynamic memory management environment
  *  creates an initialized segment with
  *  - one dynamic exclusive segment
  *  - one dynamic shared segment
  *  - error handler (can be NULL)
  *
  * Don't forget to call bbs_Context_exit on returned context if it goes out of scope
  */
 void bbs_Context_quickInit( struct bbs_Context* cpA,
 	 					    bbs_mallocFPtr mallocFPtrA,	/* function pointer to external mem alloc function (s. comment of type declaration)*/
 						    bbs_freeFPtr freeFPtrA,
 						    bbs_errorFPtr errorHandlerA );


 #endif /* bbs_CONTEXT_EM_H */
	/*
	* Copyright (C) 2008 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#ifndef bbs_CONTEXT_EM_H
	#define bbs_CONTEXT_EM_H

	/* ---- includes ----------------------------------------------------------- */

	#include "b_BasicEm/Basic.h"
	#include "b_BasicEm/MemTbl.h"
	#include "b_BasicEm/DynMemManager.h"

	/* ---- related objects --------------------------------------------------- */

	struct bbs_Context;

	/* ---- typedefs ----------------------------------------------------------- */

	/** error handler function pointer */
	typedef void ( bbs_errorFPtr )( struct bbs_Context cpA );

	/** callback handler function pointer */
	typedef uint32 ( bbs_callbackFPtr )( struct bbs_Context cpA );

	/* ---- constants ---------------------------------------------------------- */

	#define bbs_CONTEXT_MAX_ERRORS 8
	#define bbs_CONTEXT_MAX_MEM_MANAGERS 8

	#ifdef bbs_COMPACT_MESSAGE_HANDLING
	/* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
	#define bbs_ERROR_MAX_FILE_CHARS 24
	/* characters allocated for text message (minimum 1) */
	#define bbs_ERROR_MAX_TEXT_CHARS 1
	#else
	/* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
	#define bbs_ERROR_MAX_FILE_CHARS 52
	/* characters allocated for text message (minimum 1) */
	#define bbs_ERROR_MAX_TEXT_CHARS 256
	#endif

	/* defined error codes */
	#define bbs_ERR_OK 0 /* no error condition */
	#define bbs_ERR_ERROR 1 /* generic error */
	#define bbs_ERR_OUT_OF_MEMORY 2 /* malloc handler returns with NULL*/
	#define bbs_ERR_MEMORY_OVERFLOW 3 /* not enough memory in a segment or no segment */
	#define bbs_ERR_WRONG_VERSION 4 /* incompatible version in ..._memRead() */
	#define bbs_ERR_CORRUPT_DATA 5 /* corrupt data in ..._memRead()*/
	#define bbs_ERR_CALLBACK_ERROR 6 /* a defined error originiating from a callback function */

	/* ---- object definition -------------------------------------------------- */

	/** error object */
	struct bbs_Error
	{
	/* error code */
	uint32 errorE;

	/* line number */
	uint32 lineE;

	/* file name */
	char fileE[ bbs_ERROR_MAX_FILE_CHARS ];

	/* error text */
	char textE[ bbs_ERROR_MAX_TEXT_CHARS ];
	};

	/* ------------------------------------------------------------------------- */

	/** context object */
	struct bbs_Context
	{

	/* ---- private data --------------------------------------------------- */

	/** error stack */
	struct bbs_Error errStackE[ bbs_CONTEXT_MAX_ERRORS ];

	/** error stack index */
	uint32 errIndexE;

	/** memory table */
	struct bbs_MemTbl memTblE;

	/** multiple purpose dynamic memory managers */
	struct bbs_DynMemManager dynMemManagerArrE[ bbs_CONTEXT_MAX_MEM_MANAGERS ];

	/** number of used memory managers */
	uint32 dynMemManagerArrSizeE;

	/** error function handler */
	bbs_errorFPtr errorHandlerE;

	/** callback function handler */
	bbs_callbackFPtr callbackHandlerE;

	/** user-defined pointer */
	void* userPtrE;

	/* ---- public data ---------------------------------------------------- */

	};

	/* ---- associated objects ------------------------------------------------- */

	/* ---- external functions ------------------------------------------------- */

	/* ---- \ghd{ constructor/destructor } ------------------------------------- */

	/** initializes bbs_Context */
	void bbs_Context_init( struct bbs_Context* cpA );

	/** frees bbs_Context */
	void bbs_Context_exit( struct bbs_Context* cpA );

	/* ---- \ghd{ operators } -------------------------------------------------- */

	/** copy operator */
	void bbs_Context_copy( struct bbs_Context* cpA, const struct bbs_Context* srcPtrA );

	/* ---- \ghd{ query functions } -------------------------------------------- */

	/* ---- \ghd{ modify functions } ------------------------------------------- */

	/** composes an error object */
	struct bbs_Error bbs_Error_create( uint32 errorA, uint32 lineA, const char* fileA, const char* textA, ... );

	/* ---- \ghd{ memory I/O } ------------------------------------------------- */

	/* ---- \ghd{ exec functions } --------------------------------------------- */

	/**** ERROR HANDLING *******/

	/** puts an error onto the error stack (returns false if stack was already full) */
	flag bbs_Context_pushError( struct bbs_Context* cpA, struct bbs_Error errorA );

	/** takes the last error from stack and returns it (when stack is empty: returns the error at stack position 0)*/
	struct bbs_Error bbs_Context_popError( struct bbs_Context* cpA );

	/** returns the last error of stack without removing it (when stack is empty: returns the error at stack position 0)*/
	struct bbs_Error bbs_Context_peekError( struct bbs_Context* cpA );

	/** returns true if the error stack is not empty */
	flag bbs_Context_error( struct bbs_Context* cpA );

	/** sets error handler; returns pointer to previous error handler
	* Pointer to Error handler can be NULL (->no handler call)
	* The error handler is called by function pushError diectly after an error was posted
	*/
	bbs_errorFPtr bbs_Context_setErrorHandler( struct bbs_Context* cpA,
	bbs_errorFPtr errorHandlerA );

	/*******************************/

	/**** CALLBACK HANDLING ****/

	/** call the callback handler, push error if return value is != bbs_ERR_OK */
	void bbs_Context_doCallback( struct bbs_Context* cpA );

	/** sets callback handler; returns pointer to previous callback handler
	* Pointer to callback handler can be NULL (->no handler call)
	* The callback handler is called by function doCallback
	*/
	bbs_callbackFPtr bbs_Context_setCallbackHandler( struct bbs_Context* cpA,
	bbs_callbackFPtr callbackHandlerA );

	/*******************************/

	/***** MEMORY HANDLING *****/

	/** adds a static memory segment to memory table of context */
	void bbs_Context_addStaticSeg( struct bbs_Context* cpA,
	uint16* memPtrA, /* pointer to memory (32bit aligned)*/
	uint32 sizeA, /* size of memory segment in 16 bit units */
	flag sharedA, /* Indicates that this segment is to be shared among multiple objects */
	uint32 idA ); /* ID of segment, id=0: unspecified */

	/* adds a dynamic memory segment to memory table of context
	* Upon destruction of the context object any residual will be freed automatically
	*/
	void bbs_Context_addDynamicSeg( struct bbs_Context* cpA,
	bbs_mallocFPtr mallocFPtrA, /* function pointer to external mem alloc function (s. comment of type declaration)*/
	bbs_freeFPtr freeFPtrA, /* function pointer to external mem free function */
	flag sharedA, /* Indicates that this segment is to be shared among multiple objects */
	uint32 idA ); /* ID of segment, id=0: unspecified */


	/** Returns allocated memory in selected exclusive segment in units of 16bits */
	uint32 bbs_Context_exclAllocSize( struct bbs_Context* cpA, uint32 segIndexA );

	/** Returns allocated memory in selected exclusive segment in units of 16bits
	* Note that in case of static memory the return value might not reflect
	* the actually allocated memory amount.
	*/
	uint32 bbs_Context_shrdAllocSize( struct bbs_Context* cpA, uint32 segIndexA );

	/*******************************/


	/** quick compact setup for dynamic memory management environment
	* creates an initialized segment with
	* - one dynamic exclusive segment
	* - one dynamic shared segment
	* - error handler (can be NULL)
	*
	* Don't forget to call bbs_Context_exit on returned context if it goes out of scope
	*/
	void bbs_Context_quickInit( struct bbs_Context* cpA,
	bbs_mallocFPtr mallocFPtrA, /* function pointer to external mem alloc function (s. comment of type declaration)*/
	bbs_freeFPtr freeFPtrA,
	bbs_errorFPtr errorHandlerA );


	#endif /* bbs_CONTEXT_EM_H */