home *** CD-ROM | disk | FTP | other *** search
/ Kosovo Orphans' Appeal Charity CD / KosovoOrphansAppeal.iso / commercialdemos / claresmicrosupplies / pca / flexlib / h / flex
Text File  |  1996-04-29  |  12KB  |  328 lines
  1. /****************************************************************************
  2.  * This source file was written by Acorn Computers Limited. It is part of   *
  3.  * the RISCOS library for writing applications in C for RISC OS. It may be  *
  4.  * used freely in the creation of programs for Archimedes. It should be     *
  5.  * used with Acorn's C Compiler Release 3 or later.                         *
  6.  *                                                                          *
  7.  ***************************************************************************/
  8.  
  9. /*
  10.  * Title  : flex.h
  11.  * Purpose: provide memory allocation for interactive programs requiring
  12.  *          large chunks of store. Such programs must respond to memory
  13.  *          full errors.
  14.  *
  15.  *          Modified by Andy Armstrong to allow the use of Dynamic Areas
  16.  *          when used on a Risc PC. Also allows a callback function to be
  17.  *          registered. This notifies the application when a flex block moves.
  18.  *
  19.  *          Further modified by David Jackson to provide an interface with 
  20.  *          the Virtualise module. 
  21.  *
  22.  *          Modified again to work with Acorn Toolbox (Ugh!)
  23.  */
  24.  
  25. #ifndef __flex_h
  26. #define __flex_h
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30. typedef void **flex_ptr;
  31.  
  32. #include "kernel.h"
  33.  
  34. #define flex_CALLBACK
  35.  
  36. /* ----------------------------- flex_alloc -------------------------------
  37.  * Description:   Allocates n bytes of store, obtained from the Wimp.
  38.  *
  39.  * Parameters:    flex_ptr anchor -- to be used to access allocated store
  40.  *                int n -- number of bytes to be allocated
  41.  * Returns:       0 == failure, 1 == success
  42.  * Other Info:    You should pass the & of a pointer variable as the first
  43.  *                parameter. The allocated store MUST then be accessed
  44.  *                indirectly, through this, ie. (*anchor)[0] ..(*anchor)[n]
  45.  *                This is important since  the allocated store may later be
  46.  *                moved (it's a shifting heap!!). If there's not enough
  47.  *                store returns zero leaving anchor unchanged.
  48.  *
  49.  */
  50.  
  51. int flex_alloc(flex_ptr anchor, int n);
  52.  
  53.  
  54. /* ------------------------------ flex_free -------------------------------
  55.  * Description:   Frees the previously allocated store.
  56.  *
  57.  * Parameters:    flex_ptr anchor -- pointer to allocated store
  58.  * Returns:       void.
  59.  * Other Info:    *anchor will be set to 0.
  60.  *
  61.  */
  62.  
  63. void flex_free(flex_ptr anchor);
  64.  
  65.  
  66. /* ------------------------------- flex_size ------------------------------
  67.  * Description:   Informs caller of the number of bytes allocated
  68.  *
  69.  * Parameters:    flex_ptr -- pointer to allocated store
  70.  * Returns:       number of allocated bytes. 
  71.  * Other Info:    None.
  72.  *
  73.  */
  74.  
  75. int flex_size(flex_ptr);
  76.  
  77.  
  78. /* --------------------------- flex_extend --------------------------------
  79.  * Description:   Extend ot truncate the store area to have a new size.
  80.  *
  81.  * Parameters:    flex_ptr -- pointer to allocated store
  82.  *                int newsize -- new size of store
  83.  * Returns:       0 == failure, 1 == success.
  84.  * Other Info:    None.
  85.  *
  86.  */
  87.  
  88. int flex_extend(flex_ptr, int newsize);
  89.  
  90.  
  91. /* --------------------------- flex_midextend -----------------------------
  92.  * Description:   Extend or truncate store, at any point.
  93.  *
  94.  * Parameters:    flex_ptr -- pointer to allocated store
  95.  *                int at -- location within the allocated store
  96.  *                int by -- extent
  97.  * Returns:       0 == failure, 1 == success
  98.  * Other Info:    If by is +ve, then store is extended, and locations above
  99.  *                "at" are copied up by "by".
  100.  *                If by is -ve, then store is reduced, and any bytes beyond
  101.  *                "at" are copied down to "at"+"by".
  102.  *
  103.  */
  104.  
  105. int flex_midextend(flex_ptr, int at, int by);
  106.  
  107. #ifdef flex_CALLBACK
  108.  
  109. /* AA: 30.9.94 */
  110.  
  111. /* --------------------------- flex_cbfunc --------------------------------
  112.  * A function of this type may be registered for each flex block so that
  113.  * the owner of the block can be notified when the block moves
  114.  */
  115.  
  116. typedef void (*flex_cbfunc)(BOOL b4, void *handle);
  117.  
  118. /* --------------------------- flex_register -------------------------------
  119.  * Register the function to be called when a block of moves
  120.  */
  121.  
  122. void flex_register(flex_ptr anchor, flex_cbfunc cb, void *handle);
  123.  
  124. #endif
  125.  
  126.  
  127. /* ---------------------------- flex_budge --------------------------------
  128.  * Description:    Function to move flex store, when the C library needs
  129.  *                 to extend the heap.
  130.  *
  131.  * Parameters:     int n -- number of bytes needed by C library
  132.  *                 void **a -- address of acquired store.  
  133.  * Returns:        amount of store acquired.
  134.  * Other Info:     Don't call this function directly, but register it 
  135.  *                 with the C library via:
  136.  *                    _kernel_register_slotextend(flex_budge);
  137.  *                 This will cause flex store to be moved up if the C
  138.  *                 library needs to extend the heap.  Note that in this 
  139.  *                 state, you can only rely on pointers into flex blocks 
  140.  *                 across function calls which do not extend the stack and 
  141.  *                 do not call malloc.
  142.  *                 The default state is flex_dont_budge, so, if required, 
  143.  *                 this function should be registered AFTER calling 
  144.  *                 flex_init().
  145.  *
  146.  */
  147.  
  148. extern int flex_budge(int n, void **a);
  149.  
  150.  
  151. /* -------------------------- flex_dont_budge -----------------------------
  152.  * Description:   Function to refuse to move flex store, when the C library 
  153.  *                needs to extend the heap.
  154.  *
  155.  * Parameters:    int n -- number of bytes needed by C library
  156.  *                void **a -- address of acquired store.
  157.  * Returns:       amount of store acquired (always 0).
  158.  * Other Info:    Don't call this function directly, but register it 
  159.  *                with the C library via:
  160.  *                   _kernel_register_slotextend(flex_dont_budge);
  161.  *                If the C library needs to extend the heap, flex will 
  162.  *                refuse to move. This means that you can rely on pointers 
  163.  *                into flex blocks across function calls.
  164.  *                This is the DEFAULT state after flex_init().
  165.  *
  166.  */
  167.  
  168. extern int flex_dont_budge(int n, void **a);
  169.  
  170.  
  171.  
  172. /* ---------------------------- flex_init ---------------------------------
  173.  * Description:   Initialise store allocation module.
  174.  *
  175.  * Parameters:    char *program_name - name of program
  176.  *                int  *error_fd     - messages file fd.
  177.  * Returns:       void.
  178.  * Other Info:    Must be called before any other functions in this module.
  179.  *                program_name must point at a character string
  180.  *                whose lifetime is the entire program (eg a string
  181.  *                literal, or static buffer).
  182.  *                error_fd is a pointer to a file descriptor as returned
  183.  *                by MessageTrans_OpenFile - it will be used to report flex
  184.  *                errors.  If it is 0, then English default messages are used. 
  185.  *
  186.  */
  187.  
  188. void flex_init(char *program_name, int *error_fd);
  189.  
  190.  
  191.  
  192. /* ---------------------------- flex_initx ---------------------------------
  193.  * Description:   Initialise store allocation module.
  194.  *
  195.  * Parameters:    char *program_name - name of program
  196.  *                int  *error_fd     - messages file fd.
  197.  *                BOOL da      -- TRUE=use dynamic areas if available.
  198.  *                int  maxsize -- Maximum size of dynamic area.
  199.  *                BOOL virtual -- TRUE means use virtual memory.
  200.  *                                If called with virtual = FALSE, virtual
  201.  *                                memory can be switched on with 
  202.  *                                flex_virtualstart
  203.  * Returns:       void.
  204.  * Other Info:    Must be called before any other functions in this module.
  205.  *                May be replaced by flex_init
  206.  */
  207.  
  208.  
  209. void flex_initx(char *program_name, int *error_fd,BOOL da,int maxsize,BOOL virtual);
  210.  
  211. /* ---------------------------- flex_isdynamic ---------------------------------
  212.  * Description:   Enquire whether dynamic area is in use.
  213.  *
  214.  * Parameters:    void.
  215.  * Returns:       TRUE if a dynamic area is in use.
  216.  * Other Info:    None
  217.  */
  218.  
  219. BOOL flex_isdynamic(void);
  220.     
  221. /* ---------------------------- flex_VM ---------------------------------
  222.  * Description:   Enquire whether virtual memory area is in use.
  223.  *
  224.  * Parameters:    void.
  225.  * Returns:       TRUE if virtual memory is active.
  226.  * Other Info:    None
  227.  */
  228.  
  229.  
  230. BOOL flex_isVM(void);
  231.  
  232.  
  233. /* For full details of the following functions. Please read the documentation 
  234.    provided with the virtualise module.
  235. */
  236.  
  237.  
  238.  
  239.  
  240.  
  241. /* ---------------------------- flex_VMConfigure ---------------------------------
  242.  * Description:   Configure Virtulise module.
  243.  *
  244.  * Parameters:    int def   --  size of dynamic area created if passed -1 as size.
  245.  *                              Applications don't normally alter this.
  246.                   int cache --  use this much physical RAM before using VM
  247.                   int left  --  but leave at least this much free for other applications.
  248.  * Returns:       NULL if successful, otherwise an error pointer
  249.  * Other Info:    None
  250.  */
  251.  
  252. _kernel_oserror * flex_VMConfigure(int def,int cache,int left);
  253.  
  254.  
  255.  
  256. /* ---------------------------- flex_readVMConfigure ---------------------------------
  257.  * Description:   Read Virtulise module configuration.
  258.  *
  259.  * Parameters:    int *def   --  on exit contains size of dynamic area created if passed -1 as size.
  260.  *                               Applications don't normally alter this.
  261.                   int *cache --  on exit contains size of physical RAM to use before using VM
  262.                   int *left  --  on exit contains size to leave at free for other applications.
  263.  * Returns:       NULL if successful, otherwise an error pointer
  264.  * Other Info:    None
  265.  */
  266.  
  267. _kernel_oserror * flex_readVMConfigure(int *def ,int *cache,int *left);
  268.  
  269.  
  270. /* ---------------------------- flex_virtualstart ---------------------------------
  271.  * Description:   start virtual memory on flex's dynamic area.
  272.  *
  273.  * Parameters:    char *swapfile   -- pointer to filename to use as swapfile. If NULL,
  274.  *                                    Virtualise module will choose its own name (in the
  275.  *                                    scrap directory. Applications will not normally
  276.  *                                    alter this.
  277.  * Returns:       NULL if successful, otherwise an error pointer
  278.  * Other Info:    None
  279.  */
  280.  
  281. _kernel_oserror * flex_virtualstart(char * swapfile);
  282.  
  283. /* ---------------------------- flex_virtualstop ---------------------------------
  284.  * Description:   stop virtual memory on flex's dynamic area.
  285.  *
  286.  * Parameters:    void
  287.  * Returns:       NULL if successful, otherwise an error pointer
  288.  * Other Info:    None
  289.  */
  290.  
  291. _kernel_oserror * flex_virtualstop(void);
  292.  
  293.  
  294. /* ---------------------------- flex_lock ---------------------------------
  295.  * Description:   lock pages in phyical ram.
  296.  *
  297.  * Parameters:    int start -- start address to lock
  298.  *                int end   -- end   address to lock
  299.  * Returns:       NULL if successful, otherwise an error pointer
  300.  * Other Info:    None
  301.  */
  302.  
  303. _kernel_oserror * flex_lock(int start,int end);
  304.  
  305.  
  306. /* ---------------------------- flex_unlock ---------------------------------
  307.  * Description:   unlock pages in phyical ram.
  308.  *
  309.  * Parameters:    int start -- start address to unlock
  310.  *                int end   -- end   address to unlock
  311.  * Returns:       NULL if successful, otherwise an error pointer
  312.  * Other Info:    None
  313.  */
  314.  
  315. _kernel_oserror * flex_unlock(int start,int end);
  316.  
  317.  
  318.  
  319. #ifdef __cplusplus
  320. }
  321. #endif
  322. #endif
  323.  
  324. /* end flex.h */
  325.  
  326.  
  327.  
  328.