home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume34 / jpeg / part17 / jmemsys.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-12-17  |  5.3 KB  |  128 lines
  1. /*
  2.  * jmemsys.h
  3.  *
  4.  * Copyright (C) 1992, Thomas G. Lane.
  5.  * This file is part of the Independent JPEG Group's software.
  6.  * For conditions of distribution and use, see the accompanying README file.
  7.  *
  8.  * This include file defines the interface between the system-independent
  9.  * and system-dependent portions of the JPEG memory manager.  (The system-
  10.  * independent portion is jmemmgr.c; there are several different versions
  11.  * of the system-dependent portion, and of this file for that matter.)
  12.  *
  13.  * This is a "generic" skeleton that may need to be modified for particular
  14.  * systems.  It should be usable as-is on the majority of non-MSDOS machines.
  15.  */
  16.  
  17.  
  18. /*
  19.  * These two functions are used to allocate and release small chunks of
  20.  * memory (typically the total amount requested through jget_small is
  21.  * no more than 20Kb or so).  Behavior should be the same as for the
  22.  * standard library functions malloc and free; in particular, jget_small
  23.  * returns NULL on failure.  On most systems, these ARE malloc and free.
  24.  * On an 80x86 machine using small-data memory model, these manage near heap.
  25.  */
  26.  
  27. EXTERN void * jget_small PP((size_t sizeofobject));
  28. EXTERN void jfree_small PP((void * object));
  29.  
  30. /*
  31.  * These two functions are used to allocate and release large chunks of
  32.  * memory (up to the total free space designated by jmem_available).
  33.  * The interface is the same as above, except that on an 80x86 machine,
  34.  * far pointers are used.  On other systems these ARE the same as above.
  35.  */
  36.  
  37. #ifdef NEED_FAR_POINTERS    /* typically not needed except on 80x86 */
  38. EXTERN void FAR * jget_large PP((size_t sizeofobject));
  39. EXTERN void jfree_large PP((void FAR * object));
  40. #else
  41. #define jget_large(sizeofobject)    jget_small(sizeofobject)
  42. #define jfree_large(object)        jfree_small(object)
  43. #endif
  44.  
  45. /*
  46.  * The macro MAX_ALLOC_CHUNK designates the maximum number of bytes that may
  47.  * be requested in a single call on jget_large (and jget_small for that
  48.  * matter, but that case should never come into play).  This macro is needed
  49.  * to model the 64Kb-segment-size limit of far addressing on 80x86 machines.
  50.  * On machines with flat address spaces, any large constant may be used here.
  51.  */
  52.  
  53. #define MAX_ALLOC_CHUNK        1000000000L
  54.  
  55. /*
  56.  * This routine computes the total space available for allocation by
  57.  * jget_large.  If more space than this is needed, backing store will be used.
  58.  * NOTE: any memory already allocated must not be counted.
  59.  *
  60.  * There is a minimum space requirement, corresponding to the minimum
  61.  * feasible buffer sizes; jmemmgr.c will request that much space even if
  62.  * jmem_available returns zero.  The maximum space needed, enough to hold
  63.  * all working storage in memory, is also passed in case it is useful.
  64.  *
  65.  * It is OK for jmem_available to underestimate the space available (that'll
  66.  * just lead to more backing-store access than is really necessary).
  67.  * However, an overestimate will lead to failure.  Hence it's wise to subtract
  68.  * a slop factor from the true available space, especially if jget_small space
  69.  * comes from the same pool.  5% should be enough.
  70.  *
  71.  * On machines with lots of virtual memory, any large constant may be returned.
  72.  * Conversely, zero may be returned to always use the minimum amount of memory.
  73.  */
  74.  
  75. EXTERN long jmem_available PP((long min_bytes_needed, long max_bytes_needed));
  76.  
  77.  
  78. /*
  79.  * This structure holds whatever state is needed to access a single
  80.  * backing-store object.  The read/write/close method pointers are called
  81.  * by jmemmgr.c to manipulate the backing-store object; all other fields
  82.  * are private to the system-dependent backing store routines.
  83.  */
  84.  
  85. #define TEMP_NAME_LENGTH   64    /* max length of a temporary file's name */
  86.  
  87. typedef struct backing_store_struct * backing_store_ptr;
  88.  
  89. typedef struct backing_store_struct {
  90.     /* Methods for reading/writing/closing this backing-store object */
  91.     METHOD(void, read_backing_store, (backing_store_ptr info,
  92.                       void FAR * buffer_address,
  93.                       long file_offset, long byte_count));
  94.     METHOD(void, write_backing_store, (backing_store_ptr info,
  95.                        void FAR * buffer_address,
  96.                        long file_offset, long byte_count));
  97.     METHOD(void, close_backing_store, (backing_store_ptr info));
  98.     /* Private fields for system-dependent backing-store management */
  99.     /* For a typical implementation with temp files, we might need: */
  100.     FILE * temp_file;    /* stdio reference to temp file */
  101.     char temp_name[TEMP_NAME_LENGTH]; /* name of temp file */
  102.       } backing_store_info;
  103.  
  104. /*
  105.  * Initial opening of a backing-store object.  This must fill in the
  106.  * read/write/close pointers in the object.  The read/write routines
  107.  * may take an error exit if the specified maximum file size is exceeded.
  108.  * (If jmem_available always returns a large value, this routine can just
  109.  * take an error exit.)
  110.  */
  111.  
  112. EXTERN void jopen_backing_store PP((backing_store_ptr info,
  113.                     long total_bytes_needed));
  114.  
  115.  
  116. /*
  117.  * These routines take care of any system-dependent initialization and
  118.  * cleanup required.  The system methods struct address should be saved
  119.  * by jmem_init in case an error exit must be taken.  jmem_term may assume
  120.  * that all requested memory has been freed and that all opened backing-
  121.  * store objects have been closed.
  122.  * NB: jmem_term may be called more than once, and must behave reasonably
  123.  * if that happens.
  124.  */
  125.  
  126. EXTERN void jmem_init PP((external_methods_ptr emethods));
  127. EXTERN void jmem_term PP((void));
  128.