pgMemMgr.h

Go to the documentation of this file.
00001 
00002 /*  $Id: pgMemMgr.h 413 2005-01-24 02:48:56Z terry_teague $    */
00003 
00004 /* pgMemMgr.h defines the API for Paige Memory Manager. This header
00005 file also #includes "pgMachineDefs."  */
00006 
00007 /* Updated by TR Shaw, OITC, Inc. 12 Feb/20 Apr 1994 for C/C++/Pascal linkage and PPC control
00008     and for size and speed */
00009 
00010 /* New support routines provided by TR Shaw, OITC, Inc. 6 Feb 1995 */
00011 
00012 #ifndef PGMEMMGR_H
00013 #define PGMEMMGR_H
00014 
00015 #include "CPUDEFS.H"
00016 
00017 
00018 #ifdef C_LIBRARY
00019 #include <String.h>
00020 #include <stdlib.h>
00021 #endif
00022 
00023 #include "pgMTraps.h"
00024 #include "PGSETJMP.H"
00025 
00026 #ifdef PG_DEBUG
00027 #define PG_DEBUG_STATICS
00028     /* Static globals are OK in debug mode */
00029 #endif
00030 
00031 //#define PG_BIG_CHECKSUMS              
00032     /* Make huge checksums for memory trash detect */
00033 
00034 #define BIG_CHECKSUM_BYTE   0xAA        /* Byte placed into big checksum buffer */
00035 
00036 #ifdef PG_BIG_CHECKSUMS
00037 #define CHECKSUM_SIZE       2048
00038 #else
00039 #define CHECKSUM_SIZE       sizeof(long)
00040 #endif
00041 
00042 /* Debugging flags: */
00043 
00044 #define NO_DEBUG            0x0000      /* No debugging     */
00045 #define BAD_REF_CHECK       0x0001      /* Report bugus refs */
00046 #define OVERWRITE_CHECK     0x0002      /* Do a checksum at end of block */
00047 #define ACCESS_CTR_CHECK    0x0004      /* Test access counter */
00048 #define NOT_DISPOSED_CHECK  0x0008      /* Check ref is not disposed */
00049 #define ALL_MEMORY_CHECK    0x0010      /* Check ALL memory_refs each call */
00050 #define FILL_ONES_ENABLE    0x0020      /* Fill with 1's into mem_rec after dispose */
00051 #define ALL_ONES_ENABLE     0x0040      /* Fill ALL disposed memory with 1's */
00052 #define RANGE_CHECK         0x0080      /* Check range on appropriate calls */
00053 #define CURSOR_DEBUG        0x0100      /* Debug cursor out-of-sync */
00054 
00055 #define DEF_DEBUG_BITS      (BAD_REF_CHECK | OVERWRITE_CHECK | ACCESS_CTR_CHECK | NOT_DISPOSED_CHECK | RANGE_CHECK)
00056 
00057 #define MINIMUM_ID          1           /* Minimum mem_id */
00058 
00059 #define USE_ALL_RECS        -1          /* Use whole ref in UseMemoryRecord */
00060 #define REASONABLE_REC_SIZE 0x00200000  /* Don't want to go much past this */
00061 #define PURGE_VALUE_MASK    0x00FF      /* Purge value mask (strips extra flags) */
00062 #define PURGED_FLAG         0x8000      /* Flag that tells me reference is purged */
00063 #define PARTIAL_LOAD_FLAG   0x4000      /* Ref has been partially loaded */
00064 #define NO_DATA_SAVE_FLAG   0x2000      /* Data doesn't need to be saved when purged */
00065 #define PURGE_LOCK_FLAG     0x1000      /* Prevent from purging temporarily */
00066 
00067 #define CLEAR_PURGED_FLAG   0x7FFF      /* Clears the above */
00068 
00069 #define NO_PURGING_STATUS   0x00FF      /* Do not purge if purge = this */
00070 #define PURGE_NO_CHANGE     0xFFFF      /* Do not change purge status */
00071 
00072 #define PURGE_THRESHOLD     0x00010000  /* Extra amount purged for safety */
00073 #define PURGE_WORTH_IT      0x00000064  /* Amount memory has to be to be worth purging */
00074 
00075 /* "Checksum" bytes put at end of block */
00076 
00077 #define CHECKSUM_BYTE1      0x12
00078 #define CHECKSUM_BYTE2      0x34
00079 #define CHECKSUM_BYTE3      0x56
00080 #define CHECKSUM_BYTE4      0x78
00081 
00082 #define CHECKSUM_SIG        0x7777
00083 
00084 #ifdef PG_DEBUG
00085 #define NON_APP_SIZE    sizeof(mem_rec) + CHECKSUM_SIZE
00086 #else
00087 #define NON_APP_SIZE    sizeof(mem_rec)
00088 #endif
00089 
00090 #ifdef MAC_PLATFORM
00091 
00092 #define BEGIN_TIMER_DEBUG(msg) \
00093         {   unsigned long   debug_ticks = TickCount();  \
00094             char     num[14];   \
00095             num[13] = msg;
00096 
00097 #define END_TIMER_DEBUG \
00098             NumToString(TickCount() - debug_ticks, (StringPtr)num); \
00099             ++num[0];   \
00100             num[num[0]] = num[13];  \
00101             DebugStr((StringPtr)num);   }
00102 
00103 #endif
00104 
00105 #define MEM_NULL    0L
00106 
00107 typedef unsigned long memory_ref;   /* Basic memory reference */
00108 typedef memory_ref PG_FAR *memory_ref_ptr;
00109 
00110 typedef long PG_FAR *available_ptr;     /* Used for virtual memory map */
00111 typedef pg_handle PG_FAR *master_list_ptr;
00112 
00113 /* Purge function verbs:  */
00114 
00115 enum {
00116     purge_init,             /* Initialize VM */
00117     purge_memory,           /* Purge the reference */
00118     unpurge_memory,         /* Unpurge the reference */
00119     dispose_purge           /* Purged ref will be disposed */
00120 };
00121 
00122 
00123 /* Debugger proc definitions */
00124 
00125 typedef PG_FN_PASCAL (void, mem_debug_proc) (pg_error message, unsigned long what_ref);
00126 typedef PG_FN_PASCAL (pg_error, purge_proc) (memory_ref ref_to_purge, pgm_globals_ptr mem_globals, short verb);
00127 typedef PG_FN_PASCAL (long, free_memory_proc) (pgm_globals_ptr mem_globals, memory_ref dont_free, long desired_free);
00128 
00129 
00130 /* Memory Manager Global Vars (app keeps these) */
00131 
00132 struct pgm_globals {
00133     short                   signature;          /* Used for checking/debugging */
00134     pg_short_t              debug_flags;        /* Debug mode, if any */
00135     pg_handle               master_handle;      /* HANDLE for master list (Windows only) */
00136     pg_handle               spare_tire;         /* Used to free up some memory in tight situations */
00137     master_list_ptr         master_list;        /* Contains list of all active memory_refs */
00138     long                    next_master;        /* Next available space in master_list */
00139     long                    total_unpurged;     /* Total # of bytes allocated not purged */
00140     long                    max_memory;         /* Maximum memory (set by app) */
00141     long                    purge_threshold;    /* Amount extra to purge */
00142     void PG_FAR             *machine_var;       /* Machine-specific generic ptr */
00143     mem_debug_proc          debug_proc;         /* Called when a bug is detected */
00144     purge_proc              purge;              /* Called to purge/unpurge memory */
00145     free_memory_proc        free_memory;        /* Called to free up miscellaneous memory */
00146     long                    purge_ref_con;      /* Reference for purge proc */
00147     memory_ref              purge_info;         /* Machine-based purge information */
00148     memory_ref              freemem_info;       /* List of pg_ref(s) for cache feature (2.0) */
00149     long                    next_mem_id;        /* Used for unique ID's assigned to refs */
00150     long                    current_id;         /* ID to use for MemoryAlloc's */
00151     long                    active_id;          /* Which ID to suppress, if any, for purging */
00152     long                    last_message;       /* Last message in exception handling */
00153     pg_fail_info_ptr        top_fail_info;      /* Current exception in linked list */
00154     void PG_FAR *           last_ref;           /* Last reference - used by external failure processing TRS/OITC */
00155     pg_error_handler        last_handler;       /* Last app handler before Paige */
00156     pg_error                last_error;         /* Last reported error */
00157 #ifdef PG_DEBUG
00158     memory_ref              debug_check;        /* Used for special-case debugging */
00159     memory_ref              dispose_check;      /* Used for special-case debugging on DisposeMemory */
00160     short                   debug_access;       /* Used with above field */
00161 #endif
00162     void PG_FAR             *app_globals;       /* Ptr to globals for PAIGE, etc. */
00163     long                    creator;            /* For Mac file I/O */
00164     long                    fileType;           /* For Mac file I/O */
00165 };
00166 
00167 
00168 #ifdef PG_DEBUG
00169 #ifdef PG_DEBUG_STATICS
00170 extern pgm_globals_ptr  debug_globals;
00171 #endif
00172 #endif
00173 
00174 
00175 /* Memory ref's internal struct (hidden from app) which is placed in the block: */
00176 
00177 struct mem_rec {
00178     short               rec_size;       /* Record size */
00179     short               extend_size;    /* Amount of extra slop to extend */
00180     long                num_recs;       /* Current number of records */
00181     long                real_num_recs;  /* Actual number of records */
00182     long                master_index;   /* Where it is stored in master_list */
00183     short               access;         /* Access counter */
00184     pg_short_t          purge;          /* Purge priority and status */
00185     long                mem_id;         /* Special ID assigned to memory_ref */
00186     unsigned long       qty_used;       /* Nbr. of times accessed */
00187     pgm_globals_ptr     globals;        /* Globals refs */
00188 };
00189 typedef struct mem_rec mem_rec;
00190 typedef mem_rec PG_FAR *mem_rec_ptr;
00191 
00192 
00193 #ifdef __cplusplus
00194 extern  "C" {
00195 #endif
00196 
00197 
00198 /* Main function definitions */
00199 
00200 extern PG_PASCAL (void) pgMemStartup (pgm_globals_ptr mem_globals, long max_memory);
00201 extern PG_PASCAL (void) pgMemShutdown (pgm_globals_ptr mem_globals);
00202 extern PG_PASCAL (memory_ref) DisposeMemory (memory_ref ref);
00203 extern PG_PASCAL (memory_ref) DisposeNonNilMemory (memory_ref ref);
00204 extern PG_PASCAL (memory_ref) MemoryAllocID (pgm_globals_ptr globals,
00205         pg_short_t rec_size, long num_recs, short extend_size, long mem_id);
00206 extern PG_PASCAL (memory_ref) MemoryAllocClearID (pgm_globals_ptr globals,
00207         pg_short_t rec_size, long num_recs, short extend_size, long mem_id);
00208 extern PG_PASCAL (memory_ref) MemoryDuplicate (memory_ref src_ref);
00209 extern PG_PASCAL (memory_ref) MemoryDuplicateID (memory_ref src_ref, long mem_id);
00210 extern PG_PASCAL (void) MemoryCopy (memory_ref src_ref, memory_ref target_ref); 
00211 extern PG_PASCAL (memory_ref) MemoryRecover (void PG_FAR *ptr); 
00212 extern PG_PASCAL (void PG_FAR*) UseMemory (memory_ref ref);
00213 extern PG_PASCAL (void PG_FAR*) UseMemoryRecord (memory_ref ref, long wanted_rec,
00214             long seq_recs_used, pg_boolean first_use);
00215 extern PG_PASCAL (void) GetMemoryRecord (memory_ref ref, long wanted_rec,
00216             void PG_FAR *record);
00217 extern PG_PASCAL (void PG_FAR*) UseForLongTime(memory_ref ref);
00218 extern PG_PASCAL (void) SetMemorySize (memory_ref ref_to_size, long wanted_size);
00219 extern PG_PASCAL (void) SetMemoryRecSize (memory_ref ref, pg_short_t new_rec_size, short extend_size);
00220 extern PG_PASCAL (void) DisposeAllMemory (pgm_globals_ptr mem_globals, long memory_id);
00221 extern PG_PASCAL (void) PurgeAllMemory (pgm_globals_ptr mem_globals, long memory_id);
00222 extern PG_PASCAL (void) UnuseAllMemory (pgm_globals_ptr mem_globals, long memory_id);
00223 extern PG_PASCAL (long) GetAllMemorySize (pgm_globals_ptr mem_globals, long memory_id,
00224             pg_boolean return_byte_size);
00225 extern PG_PASCAL (void PG_FAR*) InsertMemory (memory_ref ref, long offset, long insert_size);
00226 extern PG_PASCAL (void PG_FAR*) AppendMemory (memory_ref ref, long append_size, pg_boolean zero_fill);
00227 extern PG_PASCAL (void) DeleteMemory (memory_ref ref, long offset, long delete_size);
00228 extern PG_PASCAL (void) SetMemoryPurge (memory_ref ref, short purge_priority,
00229         pg_boolean no_data_save);
00230 extern PG_PASCAL (memory_ref) InitMemoryRef (pgm_globals_ptr mem_globals, pg_handle base_ref);
00231 extern PG_PASCAL (memory_ref) ForceMinimumMemorySize (memory_ref ref_to_size);
00232 extern PG_PASCAL (pg_error) MemoryPurge (pgm_globals_ptr globals, long minimum_amount,
00233         memory_ref mask_ref);
00234 extern PG_PASCAL (void) InitVirtualMemory (pgm_globals_ptr globals, purge_proc purge_function,
00235         long ref_con);
00236 extern PG_PASCAL (void) UnuseMemory (memory_ref ref);
00237 extern PG_PASCAL (long) GetMemorySize (memory_ref ref);
00238 extern PG_PASCAL (long) GetByteSize (memory_ref ref);
00239 extern PG_PASCAL (short) GetMemoryRecSize (memory_ref ref);
00240 extern PG_PASCAL (pgm_globals_ptr) GetGlobalsFromRef (memory_ref ref);
00241 extern PG_PASCAL (void) UnuseAndDispose (memory_ref ref);
00242 extern PG_PASCAL (long) GetMemoryRefID(memory_ref ref);
00243 extern PG_PASCAL (void) SetMemoryRefID(memory_ref ref, long mem_id);
00244 extern PG_PASCAL (short) GetAccessCtr (memory_ref ref);
00245 extern PG_PASCAL (long) pgUniqueMemoryID (pgm_globals_ptr globals);
00246 extern PG_PASCAL (long) GetMemoryRefID(memory_ref ref);
00247 extern PG_PASCAL (void) ChangeAllMemoryID(pgm_globals_ptr mem_globals, long orig_id, long new_id);
00248 extern PG_PASCAL (long) pgGetByteSize (pg_short_t rec_size, long num_recs);
00249 extern PG_PASCAL (memory_ref) pgAllocateNewRef (pgm_globals_ptr mem_globals, pg_short_t rec_size,
00250         long num_recs, short extend_size, short zero_fill);
00251 extern PG_PASCAL (void) DisposeFailedMemory (memory_ref ref);
00252 extern PG_PASCAL (void) UnuseAllFailedMemory (pgm_globals_ptr mem_globals, long memory_id);
00253 extern PG_PASCAL (void) UnuseFailedMemory (memory_ref ref);
00254 extern PG_PASCAL (void) DisposeAllFailedMemory (pgm_globals_ptr mem_globals, long memory_id);
00255 extern PG_PASCAL (pg_handle) DetachMemory (memory_ref ref);
00256 extern PG_PASCAL (void) pgMemInsert (memory_ref ref, long offset, long byte_size, long block_size);
00257 extern PG_PASCAL (void) pgMemDelete (memory_ref ref, long offset, long byte_size, long block_size);
00258 extern PG_PASCAL (void) pgBlockMove (const void PG_FAR *src, void PG_FAR *dest, long block_size);
00259 extern PG_PASCAL (short) pgCheckReference (memory_ref ref);
00260 extern PG_PASCAL (pg_error) pgStandardPurgeProc (memory_ref ref_to_purge, pgm_globals_ptr mem_globals, short verb);
00261 extern PG_PASCAL (long) pgStandardFreeProc (pgm_globals_ptr mem_globals, memory_ref dont_free ,long desired_free);
00262 extern PG_PASCAL (pg_short_t) GetMemoryPurge (memory_ref ref);
00263 
00264 #ifdef C_LIBRARY
00265 #define pgFillBlock(block,block_size,value) memset((block),(value),(size_t)(block_size))
00266 #else
00267 extern PG_PASCAL (void) pgFillBlock (void PG_FAR *block, long block_size, char value);
00268 #endif
00269 
00270 /* The following are available only in debug mode */
00271 
00272 #ifdef PG_DEBUG
00273 
00274 extern PG_PASCAL (short) pgCheckReference (memory_ref ref);
00275 
00276 #ifdef PG_DEBUG_STATICS
00277 extern PG_PASCAL (long) TotalPaigeMemory (void);
00278 #endif
00279 extern PG_PASCAL (pg_boolean) pgCheckAllMemoryRefs (void);
00280 #endif
00281 
00282 #ifdef NO_C_INLINE
00283 extern PG_PASCAL (memory_ref) MemoryAlloc (pgm_globals_ptr globals, pg_short_t rec_size,
00284         long num_recs, short extend_size);
00285 extern PG_PASCAL (memory_ref) MemoryAllocClear (pgm_globals_ptr globals, pg_short_t rec_size,
00286         long num_recs, short extend_size);
00287 #else
00288 #define MemoryAlloc(globals,rec_size,num_recs,extend_size)  pgAllocateNewRef((globals),rec_size,num_recs,extend_size,FALSE)
00289 #define MemoryAllocClear(globals,rec_size,num_recs,extend_size)  pgAllocateNewRef((globals),rec_size,num_recs,extend_size,TRUE)
00290 #endif
00291 
00292 
00293 /* TRS/OITC additions */
00294 
00295 extern PG_PASCAL (long) MemoryToCStr(memory_ref ref);
00296 extern PG_PASCAL (long) MemoryToPStr(memory_ref ref);
00297 extern PG_PASCAL (long) CStrToMemory(memory_ref ref);
00298 extern PG_PASCAL (long) PStrToMemory(memory_ref ref);
00299 extern PG_PASCAL (char PG_FAR *) UseMemoryToCStr(memory_ref ref);
00300 extern PG_PASCAL (pg_char_ptr) UseMemoryToPStr(memory_ref ref);
00301 extern PG_PASCAL (void) UnuseMemoryFromCStr(memory_ref ref);
00302 extern PG_PASCAL (void) UnuseMemoryFromPStr(memory_ref ref);
00303 extern PG_PASCAL (void) UnuseAndZero(memory_ref ref);
00304 extern PG_PASCAL (memory_ref) DisposeNonNilFailedMemory (memory_ref ref);
00305 extern PG_PASCAL (memory_ref) DuplicateNonNilMemory (memory_ref ref);
00306 extern PG_PASCAL (pg_boolean) EqualMemory (memory_ref ref1, memory_ref ref2);
00307 extern PG_PASCAL (memory_ref) Bytes2Memory (pgm_globals_ptr mem_globals, const pg_bits8_ptr data, short char_size, long length);
00308 #ifdef NO_C_INLINE
00309 extern PG_PASCAL (memory_ref) PString2Memory (pgm_globals_ptr mem_globals, const pg_p_string_ptr string);
00310 extern PG_PASCAL (memory_ref) CString2Memory (pgm_globals_ptr mem_globals, const pg_c_string_ptr string);
00311 #else
00312 #define PString2Memory(mem_globals,string) Bytes2Memory (mem_globals, (pg_bits8_ptr)string, sizeof(pg_char), string[0] + 1)
00313 #define CString2Memory(mem_globals,string) Bytes2Memory (mem_globals, (pg_bits8_ptr)string, sizeof(pg_char), pgCStrLength(string) + 1)
00314 #endif
00315 
00316 
00317 /* pgSourceDebugBreak is used for PAIGE source code developers. Its purpose is to break into
00318 the high-level debugger of the development system. When MemMgr detects an error, it jumps
00319 to this function if you have defined SOURCE_LEVEL_DEBUG in CPUDEFS.H. */
00320 
00321 #ifdef SOURCE_LEVEL_DEBUG
00322 extern char pgSourceDebugBreak (memory_ref offending_ref, char *debug_str);
00323 #else
00324 #define pgSourceDebugBreak(offending_ref,debug_str) 
00325 #endif
00326 
00327 
00328 #ifdef __cplusplus
00329     }
00330 #endif
00331 
00332 
00333 #endif

Generated on Wed May 31 18:19:59 2006 for frontierkernel 10.1.10a by  doxygen 1.4.6