libs/jpeg6/jmemsys.h

   1 /*\r
   2 \r
   3  * jmemsys.h\r
   4 \r
   5  *\r
   6 \r
   7  * Copyright (C) 1992-1994, Thomas G. Lane.\r
   8 \r
   9  * This file is part of the Independent JPEG Group's software.\r
  10 \r
  11  * For conditions of distribution and use, see the accompanying README file.\r
  12 \r
  13  *\r
  14 \r
  15  * This include file defines the interface between the system-independent\r
  16 \r
  17  * and system-dependent portions of the JPEG memory manager.  No other\r
  18 \r
  19  * modules need include it.  (The system-independent portion is jmemmgr.c;\r
  20 \r
  21  * there are several different versions of the system-dependent portion.)\r
  22 \r
  23  *\r
  24 \r
  25  * This file works as-is for the system-dependent memory managers supplied\r
  26 \r
  27  * in the IJG distribution.  You may need to modify it if you write a\r
  28 \r
  29  * custom memory manager.  If system-dependent changes are needed in\r
  30 \r
  31  * this file, the best method is to #ifdef them based on a configuration\r
  32 \r
  33  * symbol supplied in jconfig.h, as we have done with USE_MSDOS_MEMMGR.\r
  34 \r
  35  */\r
  36 \r
  37 \r
  38 \r
  39 \r
  40 \r
  41 /* Short forms of external names for systems with brain-damaged linkers. */\r
  42 \r
  43 \r
  44 \r
  45 #ifdef NEED_SHORT_EXTERNAL_NAMES\r
  46 \r
  47 #define jpeg_get_small          jGetSmall\r
  48 \r
  49 #define jpeg_free_small         jFreeSmall\r
  50 \r
  51 #define jpeg_get_large          jGetLarge\r
  52 \r
  53 #define jpeg_free_large         jFreeLarge\r
  54 \r
  55 #define jpeg_mem_available      jMemAvail\r
  56 \r
  57 #define jpeg_open_backing_store jOpenBackStore\r
  58 \r
  59 #define jpeg_mem_init           jMemInit\r
  60 \r
  61 #define jpeg_mem_term           jMemTerm\r
  62 \r
  63 #endif /* NEED_SHORT_EXTERNAL_NAMES */\r
  64 \r
  65 \r
  66 \r
  67 \r
  68 \r
  69 /*\r
  70 \r
  71  * These two functions are used to allocate and release small chunks of\r
  72 \r
  73  * memory.  (Typically the total amount requested through jpeg_get_small is\r
  74 \r
  75  * no more than 20K or so; this will be requested in chunks of a few K each.)\r
  76 \r
  77  * Behavior should be the same as for the standard library functions malloc\r
  78 \r
  79  * and free; in particular, jpeg_get_small must return NULL on failure.\r
  80 \r
  81  * On most systems, these ARE malloc and free.  jpeg_free_small is passed the\r
  82 \r
  83  * size of the object being freed, just in case it's needed.\r
  84 \r
  85  * On an 80x86 machine using small-data memory model, these manage near heap.\r
  86 \r
  87  */\r
  88 \r
  89 \r
  90 \r
  91 EXTERN void * jpeg_get_small JPP((j_common_ptr cinfo, size_t sizeofobject));\r
  92 \r
  93 EXTERN void jpeg_free_small JPP((j_common_ptr cinfo, void * object,\r
  94 \r
  95                                  size_t sizeofobject));\r
  96 \r
  97 \r
  98 \r
  99 /*\r
 100 \r
 101  * These two functions are used to allocate and release large chunks of\r
 102 \r
 103  * memory (up to the total free space designated by jpeg_mem_available).\r
 104 \r
 105  * The interface is the same as above, except that on an 80x86 machine,\r
 106 \r
 107  * far pointers are used.  On most other machines these are identical to\r
 108 \r
 109  * the jpeg_get/free_small routines; but we keep them separate anyway,\r
 110 \r
 111  * in case a different allocation strategy is desirable for large chunks.\r
 112 \r
 113  */\r
 114 \r
 115 \r
 116 \r
 117 EXTERN void FAR * jpeg_get_large JPP((j_common_ptr cinfo,size_t sizeofobject));\r
 118 \r
 119 EXTERN void jpeg_free_large JPP((j_common_ptr cinfo, void FAR * object,\r
 120 \r
 121                                  size_t sizeofobject));\r
 122 \r
 123 \r
 124 \r
 125 /*\r
 126 \r
 127  * The macro MAX_ALLOC_CHUNK designates the maximum number of bytes that may\r
 128 \r
 129  * be requested in a single call to jpeg_get_large (and jpeg_get_small for that\r
 130 \r
 131  * matter, but that case should never come into play).  This macro is needed\r
 132 \r
 133  * to model the 64Kb-segment-size limit of far addressing on 80x86 machines.\r
 134 \r
 135  * On those machines, we expect that jconfig.h will provide a proper value.\r
 136 \r
 137  * On machines with 32-bit flat address spaces, any large constant may be used.\r
 138 \r
 139  *\r
 140 \r
 141  * NB: jmemmgr.c expects that MAX_ALLOC_CHUNK will be representable as type\r
 142 \r
 143  * size_t and will be a multiple of sizeof(align_type).\r
 144 \r
 145  */\r
 146 \r
 147 \r
 148 \r
 149 #ifndef MAX_ALLOC_CHUNK         /* may be overridden in jconfig.h */\r
 150 \r
 151 #define MAX_ALLOC_CHUNK  1000000000L\r
 152 \r
 153 #endif\r
 154 \r
 155 \r
 156 \r
 157 /*\r
 158 \r
 159  * This routine computes the total space still available for allocation by\r
 160 \r
 161  * jpeg_get_large.  If more space than this is needed, backing store will be\r
 162 \r
 163  * used.  NOTE: any memory already allocated must not be counted.\r
 164 \r
 165  *\r
 166 \r
 167  * There is a minimum space requirement, corresponding to the minimum\r
 168 \r
 169  * feasible buffer sizes; jmemmgr.c will request that much space even if\r
 170 \r
 171  * jpeg_mem_available returns zero.  The maximum space needed, enough to hold\r
 172 \r
 173  * all working storage in memory, is also passed in case it is useful.\r
 174 \r
 175  * Finally, the total space already allocated is passed.  If no better\r
 176 \r
 177  * method is available, cinfo->mem->max_memory_to_use - already_allocated\r
 178 \r
 179  * is often a suitable calculation.\r
 180 \r
 181  *\r
 182 \r
 183  * It is OK for jpeg_mem_available to underestimate the space available\r
 184 \r
 185  * (that'll just lead to more backing-store access than is really necessary).\r
 186 \r
 187  * However, an overestimate will lead to failure.  Hence it's wise to subtract\r
 188 \r
 189  * a slop factor from the true available space.  5% should be enough.\r
 190 \r
 191  *\r
 192 \r
 193  * On machines with lots of virtual memory, any large constant may be returned.\r
 194 \r
 195  * Conversely, zero may be returned to always use the minimum amount of memory.\r
 196 \r
 197  */\r
 198 \r
 199 \r
 200 \r
 201 EXTERN long jpeg_mem_available JPP((j_common_ptr cinfo,\r
 202 \r
 203                                     long min_bytes_needed,\r
 204 \r
 205                                     long max_bytes_needed,\r
 206 \r
 207                                     long already_allocated));\r
 208 \r
 209 \r
 210 \r
 211 \r
 212 \r
 213 /*\r
 214 \r
 215  * This structure holds whatever state is needed to access a single\r
 216 \r
 217  * backing-store object.  The read/write/close method pointers are called\r
 218 \r
 219  * by jmemmgr.c to manipulate the backing-store object; all other fields\r
 220 \r
 221  * are private to the system-dependent backing store routines.\r
 222 \r
 223  */\r
 224 \r
 225 \r
 226 \r
 227 #define TEMP_NAME_LENGTH   64   /* max length of a temporary file's name */\r
 228 \r
 229 \r
 230 \r
 231 #ifdef USE_MSDOS_MEMMGR         /* DOS-specific junk */\r
 232 \r
 233 \r
 234 \r
 235 typedef unsigned short XMSH;    /* type of extended-memory handles */\r
 236 \r
 237 typedef unsigned short EMSH;    /* type of expanded-memory handles */\r
 238 \r
 239 \r
 240 \r
 241 typedef union {\r
 242 \r
 243   short file_handle;            /* DOS file handle if it's a temp file */\r
 244 \r
 245   XMSH xms_handle;              /* handle if it's a chunk of XMS */\r
 246 \r
 247   EMSH ems_handle;              /* handle if it's a chunk of EMS */\r
 248 \r
 249 } handle_union;\r
 250 \r
 251 \r
 252 \r
 253 #endif /* USE_MSDOS_MEMMGR */\r
 254 \r
 255 \r
 256 \r
 257 typedef struct backing_store_struct * backing_store_ptr;\r
 258 \r
 259 \r
 260 \r
 261 typedef struct backing_store_struct {\r
 262 \r
 263   /* Methods for reading/writing/closing this backing-store object */\r
 264 \r
 265   JMETHOD(void, read_backing_store, (j_common_ptr cinfo,\r
 266 \r
 267                                      backing_store_ptr info,\r
 268 \r
 269                                      void FAR * buffer_address,\r
 270 \r
 271                                      long file_offset, long byte_count));\r
 272 \r
 273   JMETHOD(void, write_backing_store, (j_common_ptr cinfo,\r
 274 \r
 275                                       backing_store_ptr info,\r
 276 \r
 277                                       void FAR * buffer_address,\r
 278 \r
 279                                       long file_offset, long byte_count));\r
 280 \r
 281   JMETHOD(void, close_backing_store, (j_common_ptr cinfo,\r
 282 \r
 283                                       backing_store_ptr info));\r
 284 \r
 285 \r
 286 \r
 287   /* Private fields for system-dependent backing-store management */\r
 288 \r
 289 #ifdef USE_MSDOS_MEMMGR\r
 290 \r
 291   /* For the MS-DOS manager (jmemdos.c), we need: */\r
 292 \r
 293   handle_union handle;          /* reference to backing-store storage object */\r
 294 \r
 295   char temp_name[TEMP_NAME_LENGTH]; /* name if it's a file */\r
 296 \r
 297 #else\r
 298 \r
 299   /* For a typical implementation with temp files, we need: */\r
 300 \r
 301   FILE * temp_file;             /* stdio reference to temp file */\r
 302 \r
 303   char temp_name[TEMP_NAME_LENGTH]; /* name of temp file */\r
 304 \r
 305 #endif\r
 306 \r
 307 } backing_store_info;\r
 308 \r
 309 \r
 310 \r
 311 /*\r
 312 \r
 313  * Initial opening of a backing-store object.  This must fill in the\r
 314 \r
 315  * read/write/close pointers in the object.  The read/write routines\r
 316 \r
 317  * may take an error exit if the specified maximum file size is exceeded.\r
 318 \r
 319  * (If jpeg_mem_available always returns a large value, this routine can\r
 320 \r
 321  * just take an error exit.)\r
 322 \r
 323  */\r
 324 \r
 325 \r
 326 \r
 327 EXTERN void jpeg_open_backing_store JPP((j_common_ptr cinfo,\r
 328 \r
 329                                          backing_store_ptr info,\r
 330 \r
 331                                          long total_bytes_needed));\r
 332 \r
 333 \r
 334 \r
 335 \r
 336 \r
 337 /*\r
 338 \r
 339  * These routines take care of any system-dependent initialization and\r
 340 \r
 341  * cleanup required.  jpeg_mem_init will be called before anything is\r
 342 \r
 343  * allocated (and, therefore, nothing in cinfo is of use except the error\r
 344 \r
 345  * manager pointer).  It should return a suitable default value for\r
 346 \r
 347  * max_memory_to_use; this may subsequently be overridden by the surrounding\r
 348 \r
 349  * application.  (Note that max_memory_to_use is only important if\r
 350 \r
 351  * jpeg_mem_available chooses to consult it ... no one else will.)\r
 352 \r
 353  * jpeg_mem_term may assume that all requested memory has been freed and that\r
 354 \r
 355  * all opened backing-store objects have been closed.\r
 356 \r
 357  */\r
 358 \r
 359 \r
 360 \r
 361 EXTERN long jpeg_mem_init JPP((j_common_ptr cinfo));\r
 362 \r
 363 EXTERN void jpeg_mem_term JPP((j_common_ptr cinfo));\r
 364 \r