1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef bbs_CONTEXT_EM_H 18 #define bbs_CONTEXT_EM_H 19 20 /* ---- includes ----------------------------------------------------------- */ 21 22 #include "b_BasicEm/Basic.h" 23 #include "b_BasicEm/MemTbl.h" 24 #include "b_BasicEm/DynMemManager.h" 25 26 /* ---- related objects --------------------------------------------------- */ 27 28 struct bbs_Context; 29 30 /* ---- typedefs ----------------------------------------------------------- */ 31 32 /** error handler function pointer */ 33 typedef void ( *bbs_errorFPtr )( struct bbs_Context* cpA ); 34 35 /** callback handler function pointer */ 36 typedef uint32 ( *bbs_callbackFPtr )( struct bbs_Context* cpA ); 37 38 /* ---- constants ---------------------------------------------------------- */ 39 40 #define bbs_CONTEXT_MAX_ERRORS 8 41 #define bbs_CONTEXT_MAX_MEM_MANAGERS 8 42 43 #ifdef bbs_COMPACT_MESSAGE_HANDLING 44 /* characters allocated for file name string (string is stored rightbound) (minimum 1)*/ 45 #define bbs_ERROR_MAX_FILE_CHARS 24 46 /* characters allocated for text message (minimum 1) */ 47 #define bbs_ERROR_MAX_TEXT_CHARS 1 48 #else 49 /* characters allocated for file name string (string is stored rightbound) (minimum 1)*/ 50 #define bbs_ERROR_MAX_FILE_CHARS 52 51 /* characters allocated for text message (minimum 1) */ 52 #define bbs_ERROR_MAX_TEXT_CHARS 256 53 #endif 54 55 /* defined error codes */ 56 #define bbs_ERR_OK 0 /* no error condition */ 57 #define bbs_ERR_ERROR 1 /* generic error */ 58 #define bbs_ERR_OUT_OF_MEMORY 2 /* malloc handler returns with NULL*/ 59 #define bbs_ERR_MEMORY_OVERFLOW 3 /* not enough memory in a segment or no segment */ 60 #define bbs_ERR_WRONG_VERSION 4 /* incompatible version in ..._memRead() */ 61 #define bbs_ERR_CORRUPT_DATA 5 /* corrupt data in ..._memRead()*/ 62 #define bbs_ERR_CALLBACK_ERROR 6 /* a defined error originiating from a callback function */ 63 64 /* ---- object definition -------------------------------------------------- */ 65 66 /** error object */ 67 struct bbs_Error 68 { 69 /* error code */ 70 uint32 errorE; 71 72 /* line number */ 73 uint32 lineE; 74 75 /* file name */ 76 char fileE[ bbs_ERROR_MAX_FILE_CHARS ]; 77 78 /* error text */ 79 char textE[ bbs_ERROR_MAX_TEXT_CHARS ]; 80 }; 81 82 /* ------------------------------------------------------------------------- */ 83 84 /** context object */ 85 struct bbs_Context 86 { 87 88 /* ---- private data --------------------------------------------------- */ 89 90 /** error stack */ 91 struct bbs_Error errStackE[ bbs_CONTEXT_MAX_ERRORS ]; 92 93 /** error stack index */ 94 uint32 errIndexE; 95 96 /** memory table */ 97 struct bbs_MemTbl memTblE; 98 99 /** multiple purpose dynamic memory managers */ 100 struct bbs_DynMemManager dynMemManagerArrE[ bbs_CONTEXT_MAX_MEM_MANAGERS ]; 101 102 /** number of used memory managers */ 103 uint32 dynMemManagerArrSizeE; 104 105 /** error function handler */ 106 bbs_errorFPtr errorHandlerE; 107 108 /** callback function handler */ 109 bbs_callbackFPtr callbackHandlerE; 110 111 /** user-defined pointer */ 112 void* userPtrE; 113 114 /* ---- public data ---------------------------------------------------- */ 115 116 }; 117 118 /* ---- associated objects ------------------------------------------------- */ 119 120 /* ---- external functions ------------------------------------------------- */ 121 122 /* ---- \ghd{ constructor/destructor } ------------------------------------- */ 123 124 /** initializes bbs_Context */ 125 void bbs_Context_init( struct bbs_Context* cpA ); 126 127 /** frees bbs_Context */ 128 void bbs_Context_exit( struct bbs_Context* cpA ); 129 130 /* ---- \ghd{ operators } -------------------------------------------------- */ 131 132 /** copy operator */ 133 void bbs_Context_copy( struct bbs_Context* cpA, const struct bbs_Context* srcPtrA ); 134 135 /* ---- \ghd{ query functions } -------------------------------------------- */ 136 137 /* ---- \ghd{ modify functions } ------------------------------------------- */ 138 139 /** composes an error object */ 140 struct bbs_Error bbs_Error_create( uint32 errorA, uint32 lineA, const char* fileA, const char* textA, ... ); 141 142 /* ---- \ghd{ memory I/O } ------------------------------------------------- */ 143 144 /* ---- \ghd{ exec functions } --------------------------------------------- */ 145 146 /****** ERROR HANDLING *********/ 147 148 /** puts an error onto the error stack (returns false if stack was already full) */ 149 flag bbs_Context_pushError( struct bbs_Context* cpA, struct bbs_Error errorA ); 150 151 /** takes the last error from stack and returns it (when stack is empty: returns the error at stack position 0)*/ 152 struct bbs_Error bbs_Context_popError( struct bbs_Context* cpA ); 153 154 /** returns the last error of stack without removing it (when stack is empty: returns the error at stack position 0)*/ 155 struct bbs_Error bbs_Context_peekError( struct bbs_Context* cpA ); 156 157 /** returns true if the error stack is not empty */ 158 flag bbs_Context_error( struct bbs_Context* cpA ); 159 160 /** sets error handler; returns pointer to previous error handler 161 * Pointer to Error handler can be NULL (->no handler call) 162 * The error handler is called by function pushError diectly after an error was posted 163 */ 164 bbs_errorFPtr bbs_Context_setErrorHandler( struct bbs_Context* cpA, 165 bbs_errorFPtr errorHandlerA ); 166 167 /*******************************/ 168 169 /****** CALLBACK HANDLING ******/ 170 171 /** call the callback handler, push error if return value is != bbs_ERR_OK */ 172 void bbs_Context_doCallback( struct bbs_Context* cpA ); 173 174 /** sets callback handler; returns pointer to previous callback handler 175 * Pointer to callback handler can be NULL (->no handler call) 176 * The callback handler is called by function doCallback 177 */ 178 bbs_callbackFPtr bbs_Context_setCallbackHandler( struct bbs_Context* cpA, 179 bbs_callbackFPtr callbackHandlerA ); 180 181 /*******************************/ 182 183 /******* MEMORY HANDLING *******/ 184 185 /** adds a static memory segment to memory table of context */ 186 void bbs_Context_addStaticSeg( struct bbs_Context* cpA, 187 uint16* memPtrA, /* pointer to memory (32bit aligned)*/ 188 uint32 sizeA, /* size of memory segment in 16 bit units */ 189 flag sharedA, /* Indicates that this segment is to be shared among multiple objects */ 190 uint32 idA ); /* ID of segment, id=0: unspecified */ 191 192 /* adds a dynamic memory segment to memory table of context 193 * Upon destruction of the context object any residual will be freed automatically 194 */ 195 void bbs_Context_addDynamicSeg( struct bbs_Context* cpA, 196 bbs_mallocFPtr mallocFPtrA, /* function pointer to external mem alloc function (s. comment of type declaration)*/ 197 bbs_freeFPtr freeFPtrA, /* function pointer to external mem free function */ 198 flag sharedA, /* Indicates that this segment is to be shared among multiple objects */ 199 uint32 idA ); /* ID of segment, id=0: unspecified */ 200 201 202 /** Returns allocated memory in selected exclusive segment in units of 16bits */ 203 uint32 bbs_Context_exclAllocSize( struct bbs_Context* cpA, uint32 segIndexA ); 204 205 /** Returns allocated memory in selected exclusive segment in units of 16bits 206 * Note that in case of static memory the return value might not reflect 207 * the actually allocated memory amount. 208 */ 209 uint32 bbs_Context_shrdAllocSize( struct bbs_Context* cpA, uint32 segIndexA ); 210 211 /*******************************/ 212 213 214 /** quick compact setup for dynamic memory management environment 215 * creates an initialized segment with 216 * - one dynamic exclusive segment 217 * - one dynamic shared segment 218 * - error handler (can be NULL) 219 * 220 * Don't forget to call bbs_Context_exit on returned context if it goes out of scope 221 */ 222 void bbs_Context_quickInit( struct bbs_Context* cpA, 223 bbs_mallocFPtr mallocFPtrA, /* function pointer to external mem alloc function (s. comment of type declaration)*/ 224 bbs_freeFPtr freeFPtrA, 225 bbs_errorFPtr errorHandlerA ); 226 227 228 #endif /* bbs_CONTEXT_EM_H */ 229 230