home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / system / vmem / autodocs / vmem.doc next >
Text File  |  1995-02-27  |  11KB  |  476 lines
  1. TABLE OF CONTENTS
  2.  
  3. vmem.library/--background---
  4. vmem.library/vmAllocBlock
  5. vmem.library/vmAllocData
  6. vmem.library/vmAllocMem
  7. vmem.library/vmFlush
  8. vmem.library/vmFreeBlock
  9. vmem.library/vmFreeData
  10. vmem.library/vmFreeMem
  11. vmem.library/vmLock
  12. vmem.library/vmLockData
  13. vmem.library/vmUnLock
  14. vmem.library/vmUnLockData
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21. vmem.library/--background---                     vmem.library/--background---
  22.  
  23.  
  24.                        THE ** VIRTUAL MEMORY ** LIBRARY
  25.  
  26.                                ( VERSION 1 )
  27.  
  28.                        COPYRIGHT (c) 1994 BY LEE BRAIDEN
  29.  
  30.  
  31.        These are the autodocs for programming vmem.library. VMem is a very
  32.    simple set of six (6) functions, and four (4) macros. All you need to do
  33.    to use VMem is :
  34.  
  35.        * Call vmAllocBlock (or use the macro vmAllocData) to get a control
  36.          handle. (This is used by VMem to keep track of what's happening
  37.          to your data).
  38.  
  39.        * Call vmLock (or use the macro vmLockData) to get a lock on the
  40.          data you wanna use at that time.
  41.  
  42.        * Access your data.
  43.  
  44.        * Call vmUnLock (or use the macro vmUnLockData) to unlock the data
  45.          again.
  46.  
  47.        * Call vmFreeBlock (or use the macro vmFreeData) to free the control
  48.          handle you got by calling vmAllocBlock (or using vmAllocData)
  49.  
  50.  
  51.        The macro versions of the four functions just a simple way to alloc
  52.    one element of data without the extra args required by the functions.
  53.    (The functions have extra options to cope with array use.
  54.  
  55.  
  56.        The other two (2) functions are replacements for exec.library's
  57.    AllocMem() and FreeMem() functions. They provide a few more functions
  58.    than exec's versions, including flushing Virtual Memory if exec's
  59.    AllocMem would normally fail.
  60.  
  61.        See the individual autodocs below for a more detailed explanation.
  62.  
  63. vmem.library/vmAllocBlock                           vmem.library/vmAllocBlock
  64.  
  65.    NAME   
  66.            vmAllocBlock
  67.  
  68.    SYNOPSIS
  69.            vmBlock *vmb = vmAllocBlock(ULONG size,ULONG nels,ULONG memflags)
  70.                      d0                  d0          d1          d2
  71.  
  72.    FUNCTION
  73.            Allocates a vmBlock for control of data which will use virtual
  74.        memory.
  75.  
  76.    INPUTS
  77.  
  78.        size:
  79.        -   size of each element in array
  80.        nels:
  81.        -   number of elements in array
  82.        memflags:
  83.        -   standard exec.library/AllocMem() memory attribute flags
  84.  
  85.    RESULT
  86.  
  87.        vmb:
  88.        -   Virtual memory control handle (vmBlock).This block stores
  89.            information about your data,and is passed to the other
  90.            virtual memory functions to let them know what state your
  91.            data is in.
  92.  
  93.    EXAMPLE
  94.  
  95.        vmBlock *vmb;
  96.        struct Preferences *prefs_ptr;/*largest structure I could think of*/
  97.        ULONG i;
  98.        ...
  99.  
  100.        if(!(vmb = vmAllocBlock(sizeof(struct Preferences),10,MEMF_PUBLIC)))
  101.        {
  102.            /*  vmAllocBlock failed - you're either *VERY* low on memory,
  103.                or the the path that vmem.library is using is full */
  104.  
  105.            ...
  106.  
  107.        }else
  108.        {
  109.            for(i=0;i<NUM_ELS;i++)
  110.            {
  111.                if(!(prefs_ptr = vmLock(vmb,i)))
  112.                {
  113.                    /* data lock failed - disk error , or VERY low on mem */
  114.                    ....
  115.  
  116.                }else
  117.                {
  118.                    /* you've got your data,do whatever you want with it */
  119.  
  120.                    ....
  121.  
  122.                    /*  unlock the data when you've finished with it,so vmem
  123.                        will know when it's not in use */ 
  124.  
  125.                    vmUnLock(vmb,i);
  126.  
  127.                };
  128.            };
  129.  
  130.            /*  when you've finished with all the data, free the control
  131.                block */
  132.                 
  133.           vmFreeBlock(vmb);
  134.        };
  135.  
  136.  
  137.  
  138.  
  139.    NOTES
  140.  
  141.    BUGS
  142.  
  143.        Doesn't handle saving across multiple disks/devices yet.
  144.  
  145.    SEE ALSO
  146.  
  147.        vmFreeBlock,vmLock,vmUnLock,         vmAllocData
  148.        exec.library/AllocMem autodoc (for memory flag definitions)
  149.  
  150. vmem.library/vmAllocData                             vmem.library/vmAllocData
  151.  
  152.    NAME
  153.  
  154.            vmAllocData         (MACRO)
  155.  
  156.    SYNOPSIS
  157.  
  158.            vmBlock *b = vmAllocData(ULONG blocksize,ULONG memflags);
  159.  
  160.    FUNCTION
  161.  
  162.        This is defined in Libraries/VMem.h as vmAllocBlock(blocksize,1,memfla
  163. gs)
  164.        It just Allocates a vmBlock which isn't an array,i.e. Only contains
  165.        one element.See that function's autodoc for details.
  166.            
  167.    INPUTS
  168.  
  169.    RESULT
  170.  
  171.    EXAMPLE
  172.  
  173.    NOTES
  174.  
  175.    BUGS
  176.  
  177.    SEE ALSO
  178.  
  179.        vmAllocBlock,    vmLockData,vmUnLockData,vmFreeData
  180.  
  181. vmem.library/vmAllocMem                               vmem.library/vmAllocMem
  182.  
  183.    NAME   
  184.            vmAllocMem
  185.  
  186.    SYNOPSIS
  187.            VOID *memptr = vmAllocMem(ULONG size,ULONG attrs)
  188.                    d0                  d0          d1
  189.  
  190.    FUNCTION
  191.            Identical to exec.library/AllocMem except does extra checking
  192.        and vmem flushing if needed.
  193.  
  194.    INPUTS
  195.            Indentical to exec.library/AllocMem. See that function's autodoc
  196.        for more information.
  197.  
  198.    RESULT
  199.        result:
  200.        -   Pointer to memory which was allocated,or NULL if something went
  201.            wrong.
  202.  
  203.    EXAMPLE
  204.  
  205.    NOTES
  206.  
  207.    BUGS
  208.  
  209.    SEE ALSO
  210.  
  211.         vmFreeMem,  exec.library/AllocMem
  212.  
  213. vmem.library/vmFlush                                     vmem.library/vmFlush
  214.  
  215.    NAME   
  216.            vmFlush
  217.  
  218.    SYNOPSIS
  219.            ULONG memflushed = vmFlush(ULONG memneeded,ULONG memflags);
  220.                    d0                      d0              d1
  221.  
  222.    FUNCTION
  223.            Flushes required amount unused virtual memory from the system.
  224.  
  225.    INPUTS
  226.            memneeded:
  227.            -   Amount of *ADDITIONAL* free memory you need in bytes.
  228.            memflags:
  229.            -   Type of memory to flush (standard exec.library/AllocMem
  230.                memory attributes)
  231.  
  232.    RESULT
  233.            memflushed:
  234.            -   Amount of memory you got (in bytes).
  235.  
  236.    EXAMPLE
  237.  
  238.    NOTES
  239.            memflushed is the memory that was freed into the free memory
  240.        list by this function - by the time it returns,another program
  241.        might have pulled it from under you, so check results of vmAllocMem
  242.        even if this function tells you there's enough mem.
  243.  
  244.    BUGS
  245.  
  246.    SEE ALSO
  247.  
  248. vmem.library/vmFreeBlock                             vmem.library/vmFreeBlock
  249.  
  250.    NAME   
  251.            vmFreeBlock
  252.  
  253.    SYNOPSIS
  254.            void vmFreeBlock(vmBlock *b)
  255.                    a0
  256.  
  257.    FUNCTION
  258.            Frees a virtual memory control block when you have finished with
  259.        it.
  260.  
  261.    INPUTS
  262.            b:
  263.            -   pointer to the virtual memory block to free.
  264.  
  265.    RESULT
  266.            Frees all memory used for this virtual memory data,deletes any
  267.        virtual memory files which exist on disk,and does other general
  268.        cleanup stuff.
  269.  
  270.    EXAMPLE
  271.  
  272.        See vmAllocBlock()'s example above.
  273.  
  274.    NOTES
  275.  
  276.    BUGS
  277.  
  278.    SEE ALSO
  279.  
  280.        vmAllocBlock,vmLock,vmUnLock,        vmFreeData
  281.  
  282. vmem.library/vmFreeData                               vmem.library/vmFreeData
  283.  
  284.    NAME
  285.  
  286.            vmFreeData          (MACRO)   
  287.  
  288.    SYNOPSIS
  289.  
  290.            void vmFreeData(vmBlock *);
  291.  
  292.    FUNCTION
  293.  
  294.        This is defined in Libraries/VMem.h as vmFreeBlock(b). It does exactly
  295.        the same as vmFreeBlock,and is only provided to make the macros
  296.        vmAllocData,vmLockData,and vmUnLockData more programmer-friendly.
  297.        See vmFreeBlock()'s autodoc for usage.
  298.  
  299.    INPUTS
  300.  
  301.    RESULT
  302.  
  303.    EXAMPLE
  304.  
  305.    NOTES
  306.  
  307.    BUGS
  308.  
  309.    SEE ALSO
  310.  
  311.        vmFreeBlock,     vmAllocData,vmLockData,vmUnLockData
  312.  
  313. vmem.library/vmFreeMem                                 vmem.library/vmFreeMem
  314.  
  315.    NAME   
  316.            vmFreeMem
  317.  
  318.    SYNOPSIS
  319.            VOID vmFreeMem(VOID *memptr,ULONG size)
  320.                                d0          d1
  321.  
  322.    FUNCTION
  323.            Identical to exec.library/FreeMem except does extra checking.
  324.  
  325.    INPUTS
  326.            Indentical to exec.library/AllocMem. See that function's autodoc
  327.        for more information.
  328.  
  329.    RESULT
  330.  
  331.    EXAMPLE
  332.  
  333.    NOTES
  334.  
  335.    BUGS
  336.  
  337.    SEE ALSO
  338.  
  339.         vmAllocMem,     exec.library/FreeMem
  340.  
  341. vmem.library/vmLock                                       vmem.library/vmLock
  342.  
  343.    NAME   
  344.            vmLock
  345.  
  346.    SYNOPSIS
  347.            VOID *ptr = vmLock(vmBlock *b,ULONG el)
  348.                  d0                  a0       d0
  349.  
  350.    FUNCTION
  351.            Locks a particular element of virtual memory data for use.
  352.  
  353.    INPUTS
  354.            b:
  355.            -   Virtual Memory control block which required data belongs to.
  356.  
  357.            el:
  358.            -   Particular element of data that you want to access.
  359.  
  360.    RESULT
  361.  
  362.            ptr:
  363.            -   Actual memory address of data element which is now safe to
  364.                access.
  365.  
  366.    EXAMPLE
  367.  
  368.        See vmAllocBlock()'s example above.
  369.  
  370.    NOTES
  371.  
  372.    BUGS
  373.  
  374.    SEE ALSO
  375.  
  376.        vmAllocBlock,vmUnLock,vmFreeBlock,        vmLockData
  377.  
  378. vmem.library/vmLockData                               vmem.library/vmLockData
  379.  
  380.    NAME   
  381.  
  382.        vmLockData          (MACRO)
  383.  
  384.    SYNOPSIS
  385.  
  386.        VOID *memptr = vmLockData(vmBlock *blk)
  387.  
  388.    FUNCTION
  389.  
  390.        This is defined in Libraries/VMem.h as vmLock(blk,0).
  391.        It just locks a block of memory for a vmBlock with one element.
  392.        See that function's autodoc for details
  393.  
  394.    INPUTS
  395.  
  396.    RESULT
  397.  
  398.    EXAMPLE
  399.  
  400.    NOTES
  401.  
  402.    BUGS
  403.  
  404.    SEE ALSO
  405.  
  406.        vmLock, vmAllocData,vmUnLockData,vmFreeData
  407.  
  408. vmem.library/vmUnLock                                   vmem.library/vmUnLock
  409.  
  410.    NAME   
  411.            vmUnLock
  412.  
  413.    SYNOPSIS
  414.            void vmUnLock(vmBlock *b,ULONG el)
  415.                                a0          d0
  416.  
  417.    FUNCTION
  418.            Unlocks a virtual memory data element which was locked by
  419.        vmLock().
  420.  
  421.    INPUTS
  422.        b:
  423.        -   pointer to the virtual memory control block for the data.
  424.        el:
  425.        -   The number of the element to unlock.
  426.  
  427.    RESULT
  428.            Unlocks the data.When data has no more locks on it,
  429.        and real memory gets low,the data will be saved to a vmem file,
  430.        and the real memory is freed.
  431.  
  432.    EXAMPLE
  433.  
  434.        See vmAllocBlock()'s example, above.
  435.  
  436.    NOTES
  437.            Note that this function takes the NUMBER of the element you
  438.        wish to unlock,and not a pointer to the data as you might expect.
  439.  
  440.    BUGS
  441.  
  442.    SEE ALSO
  443.  
  444.        vmAllocBlock,vmLock,vmFreeBlock,      vmUnLockData
  445.  
  446. vmem.library/vmUnLockData                           vmem.library/vmUnLockData
  447.  
  448.    NAME   
  449.  
  450.            vmUnLockData        (MACRO)
  451.  
  452.    SYNOPSIS
  453.  
  454.            void vmUnLockData(vmBlock *blk);
  455.  
  456.    FUNCTION
  457.  
  458.        This is defined in Libraries/VMem.h as vmUnLock(blk,0). It just
  459.        unlocks a block of memory for a vmBlock with one element. See that
  460.        function's autodoc for details.
  461.  
  462.    INPUTS
  463.  
  464.    RESULT
  465.  
  466.    EXAMPLE
  467.  
  468.    NOTES
  469.  
  470.    BUGS
  471.  
  472.    SEE ALSO
  473.  
  474.        vmUnLock,   vmAllocData,vmLockData,vmFreeData
  475.  
  476.