00001 /* 00002 * jmemsys.h 00003 * 00004 * Copyright (C) 1992-1997, Thomas G. Lane. 00005 * This file is part of the Independent JPEG Group's software. 00006 * For conditions of distribution and use, see the accompanying README file. 00007 * 00008 * This include file defines the interface between the system-independent 00009 * and system-dependent portions of the JPEG memory manager. No other 00010 * modules need include it. (The system-independent portion is jmemmgr.c; 00011 * there are several different versions of the system-dependent portion.) 00012 * 00013 * This file works as-is for the system-dependent memory managers supplied 00014 * in the IJG distribution. You may need to modify it if you write a 00015 * custom memory manager. If system-dependent changes are needed in 00016 * this file, the best method is to #ifdef them based on a configuration 00017 * symbol supplied in jconfig.h, as we have done with USE_MSDOS_MEMMGR 00018 * and USE_MAC_MEMMGR. 00019 */ 00020 00021 00022 /* Short forms of external names for systems with brain-damaged linkers. */ 00023 00024 #ifdef NEED_SHORT_EXTERNAL_NAMES 00025 #define jpeg_get_small jGetSmall 00026 #define jpeg_free_small jFreeSmall 00027 #define jpeg_get_large jGetLarge 00028 #define jpeg_free_large jFreeLarge 00029 #define jpeg_mem_available jMemAvail 00030 #define jpeg_open_backing_store jOpenBackStore 00031 #define jpeg_mem_init jMemInit 00032 #define jpeg_mem_term jMemTerm 00033 #endif /* NEED_SHORT_EXTERNAL_NAMES */ 00034 00035 00036 /* 00037 * These two functions are used to allocate and release small chunks of 00038 * memory. (Typically the total amount requested through jpeg_get_small is 00039 * no more than 20K or so; this will be requested in chunks of a few K each.) 00040 * Behavior should be the same as for the standard library functions malloc 00041 * and free; in particular, jpeg_get_small must return NULL on failure. 00042 * On most systems, these ARE malloc and free. jpeg_free_small is passed the 00043 * size of the object being freed, just in case it's needed. 00044 * On an 80x86 machine using small-data memory model, these manage near heap. 00045 */ 00046 00047 EXTERN(void *) jpeg_get_small JPP((j_common_ptr cinfo, size_t sizeofobject)); 00048 EXTERN(void) jpeg_free_small JPP((j_common_ptr cinfo, void * object, 00049 size_t sizeofobject)); 00050 00051 /* 00052 * These two functions are used to allocate and release large chunks of 00053 * memory (up to the total free space designated by jpeg_mem_available). 00054 * The interface is the same as above, except that on an 80x86 machine, 00055 * far pointers are used. On most other machines these are identical to 00056 * the jpeg_get/free_small routines; but we keep them separate anyway, 00057 * in case a different allocation strategy is desirable for large chunks. 00058 */ 00059 00060 EXTERN(void FAR *) jpeg_get_large JPP((j_common_ptr cinfo, 00061 size_t sizeofobject)); 00062 EXTERN(void) jpeg_free_large JPP((j_common_ptr cinfo, void FAR * object, 00063 size_t sizeofobject)); 00064 00065 /* 00066 * The macro MAX_ALLOC_CHUNK designates the maximum number of bytes that may 00067 * be requested in a single call to jpeg_get_large (and jpeg_get_small for that 00068 * matter, but that case should never come into play). This macro is needed 00069 * to model the 64Kb-segment-size limit of far addressing on 80x86 machines. 00070 * On those machines, we expect that jconfig.h will provide a proper value. 00071 * On machines with 32-bit flat address spaces, any large constant may be used. 00072 * 00073 * NB: jmemmgr.c expects that MAX_ALLOC_CHUNK will be representable as type 00074 * size_t and will be a multiple of sizeof(align_type). 00075 */ 00076 00077 #ifndef MAX_ALLOC_CHUNK /* may be overridden in jconfig.h */ 00078 #define MAX_ALLOC_CHUNK 1000000000L 00079 #endif 00080 00081 /* 00082 * This routine computes the total space still available for allocation by 00083 * jpeg_get_large. If more space than this is needed, backing store will be 00084 * used. NOTE: any memory already allocated must not be counted. 00085 * 00086 * There is a minimum space requirement, corresponding to the minimum 00087 * feasible buffer sizes; jmemmgr.c will request that much space even if 00088 * jpeg_mem_available returns zero. The maximum space needed, enough to hold 00089 * all working storage in memory, is also passed in case it is useful. 00090 * Finally, the total space already allocated is passed. If no better 00091 * method is available, cinfo->mem->max_memory_to_use - already_allocated 00092 * is often a suitable calculation. 00093 * 00094 * It is OK for jpeg_mem_available to underestimate the space available 00095 * (that'll just lead to more backing-store access than is really necessary). 00096 * However, an overestimate will lead to failure. Hence it's wise to subtract 00097 * a slop factor from the true available space. 5% should be enough. 00098 * 00099 * On machines with lots of virtual memory, any large constant may be returned. 00100 * Conversely, zero may be returned to always use the minimum amount of memory. 00101 */ 00102 00103 EXTERN(long) jpeg_mem_available JPP((j_common_ptr cinfo, 00104 long min_bytes_needed, 00105 long max_bytes_needed, 00106 long already_allocated)); 00107 00108 00109 /* 00110 * This structure holds whatever state is needed to access a single 00111 * backing-store object. The read/write/close method pointers are called 00112 * by jmemmgr.c to manipulate the backing-store object; all other fields 00113 * are private to the system-dependent backing store routines. 00114 */ 00115 00116 #define TEMP_NAME_LENGTH 64 /* max length of a temporary file's name */ 00117 00118 00119 #ifdef USE_MSDOS_MEMMGR /* DOS-specific junk */ 00120 00121 typedef unsigned short XMSH; /* type of extended-memory handles */ 00122 typedef unsigned short EMSH; /* type of expanded-memory handles */ 00123 00124 typedef union { 00125 short file_handle; /* DOS file handle if it's a temp file */ 00126 XMSH xms_handle; /* handle if it's a chunk of XMS */ 00127 EMSH ems_handle; /* handle if it's a chunk of EMS */ 00128 } handle_union; 00129 00130 #endif /* USE_MSDOS_MEMMGR */ 00131 00132 #ifdef USE_MAC_MEMMGR /* Mac-specific junk */ 00133 #include <Files.h> 00134 #endif /* USE_MAC_MEMMGR */ 00135 00136 00137 typedef struct backing_store_struct * backing_store_ptr; 00138 00139 typedef struct backing_store_struct { 00140 /* Methods for reading/writing/closing this backing-store object */ 00141 JMETHOD(void, read_backing_store, (j_common_ptr cinfo, 00142 backing_store_ptr info, 00143 void FAR * buffer_address, 00144 long file_offset, long byte_count)); 00145 JMETHOD(void, write_backing_store, (j_common_ptr cinfo, 00146 backing_store_ptr info, 00147 void FAR * buffer_address, 00148 long file_offset, long byte_count)); 00149 JMETHOD(void, close_backing_store, (j_common_ptr cinfo, 00150 backing_store_ptr info)); 00151 00152 /* Private fields for system-dependent backing-store management */ 00153 #ifdef USE_MSDOS_MEMMGR 00154 /* For the MS-DOS manager (jmemdos.c), we need: */ 00155 handle_union handle; /* reference to backing-store storage object */ 00156 char temp_name[TEMP_NAME_LENGTH]; /* name if it's a file */ 00157 #else 00158 #ifdef USE_MAC_MEMMGR 00159 /* For the Mac manager (jmemmac.c), we need: */ 00160 short temp_file; /* file reference number to temp file */ 00161 FSSpec tempSpec; /* the FSSpec for the temp file */ 00162 char temp_name[TEMP_NAME_LENGTH]; /* name if it's a file */ 00163 #else 00164 /* For a typical implementation with temp files, we need: */ 00165 FILE * temp_file; /* stdio reference to temp file */ 00166 char temp_name[TEMP_NAME_LENGTH]; /* name of temp file */ 00167 #endif 00168 #endif 00169 } backing_store_info; 00170 00171 00172 /* 00173 * Initial opening of a backing-store object. This must fill in the 00174 * read/write/close pointers in the object. The read/write routines 00175 * may take an error exit if the specified maximum file size is exceeded. 00176 * (If jpeg_mem_available always returns a large value, this routine can 00177 * just take an error exit.) 00178 */ 00179 00180 EXTERN(void) jpeg_open_backing_store JPP((j_common_ptr cinfo, 00181 backing_store_ptr info, 00182 long total_bytes_needed)); 00183 00184 00185 /* 00186 * These routines take care of any system-dependent initialization and 00187 * cleanup required. jpeg_mem_init will be called before anything is 00188 * allocated (and, therefore, nothing in cinfo is of use except the error 00189 * manager pointer). It should return a suitable default value for 00190 * max_memory_to_use; this may subsequently be overridden by the surrounding 00191 * application. (Note that max_memory_to_use is only important if 00192 * jpeg_mem_available chooses to consult it ... no one else will.) 00193 * jpeg_mem_term may assume that all requested memory has been freed and that 00194 * all opened backing-store objects have been closed. 00195 */ 00196 00197 EXTERN(long) jpeg_mem_init JPP((j_common_ptr cinfo)); 00198 EXTERN(void) jpeg_mem_term JPP((j_common_ptr cinfo));