home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / dev / cmanual-3.0.lha / CManual / Intuition / Miscellaneous / Miscellaneous.doc < prev    next >
Text File  |  1993-10-12  |  34KB  |  1,007 lines
  1. 9    MISCELLANEOUS
  2.  
  3. 9.1  INTRODUCTION
  4.  
  5. This is the last chapter about Intuition, and we will therefore
  6. finish of by discussing some special features.
  7.  
  8.  
  9.  
  10. 9.2  MEMORY
  11.  
  12. If you write C programs you will often need to allocate some
  13. memory. This process is normally referred as "dynamic memory
  14. allocation" and is used whenever your program needs some more
  15. memory while it is running.
  16.  
  17. When you allocate memory you need to specify how much you want,
  18. and what type of memory (Fast or Chip). "Exec" will then try to
  19. allocated the memory, and will return a pointer to the memory,
  20. or NULL if it could not find a block big enough.
  21.  
  22. Once you have allocated the memory, you can use it as much as
  23. you want. You just have to remember that before the program
  24. terminates it must have deallocated all allocated memory. If
  25. you forget to deallocate the memory when you leave, it will
  26. be lost, and the only way to get it back is to reboot.
  27.  
  28.  
  29.  
  30. 9.2.1  ALLOCATE MEMORY
  31.  
  32. You usually use the function AllocMem() if you want to allocate
  33. memory. You only need to specify how much memory you need, and
  34. what type of memory (Chip, Fast etc), and AllocMem() will
  35. return a pointer to the new memory, or NULL if no memory could
  36. be allocated.
  37.  
  38. Synopsis: memory = AllocMem( size, type );
  39.  
  40. memory:   (void *) Pointer to the new allocated memory, or NULL
  41.           if no memory could be allocated. Remember! Never use
  42.           memory which you have not successfully allocated.
  43.  
  44. size:     (long) The size (in bytes) of the memory you want.
  45.           (AllocMem() always allocates memory in multiples of
  46.           eight bytes. So if you only ask for 9 bytes, Exec
  47.           would actually give you 16 Bytes (2*8).)
  48.  
  49. type:     (long) You need to choose one of the three following
  50.           types of memory (see chapter 0 INTRODUCTION for more
  51.           information about Chip and Fast memory). (The flags
  52.           are declared in the header file "exec/memory.h".)
  53.  
  54.           MEMF_CHIP   Chip memory. This memory can be accessed
  55.                       by both the main processor, as well as
  56.                       the Chips. Graphics/Sound data MUST 
  57.                       therefore be placed in Chip memory. If it
  58.                       does not matter what type of memory you
  59.                       get (Fast or Chip), you should try to
  60.                       allocate Fast memory before you allocate
  61.                       Chip memory. (Chip memory is more valuable
  62.                       than Fast memory.)
  63.  
  64.           MEMF_FAST   Fast memory. This memory can only be
  65.                       accessed by the main processor. (Graphics
  66.                       and Sound data can NOT be stored in Fast
  67.                       memory, use Chip memory.) This memory is
  68.                       normally a little bit faster than Chip
  69.                       memory, since only the main processor is
  70.                       working with it, and it is not disturbed
  71.                       by the Chips.
  72.  
  73.           MEMF_PUBLIC If it does not matter what type of memory
  74.                       you get (you do not intend to use the
  75.                       memory for Graphics/Sound data), you
  76.                       should use Fast memory. However, all
  77.                       Amigas do not have Fast memory, since
  78.                       you need to by a memory expansion in
  79.                       order to get it. If want to tell Exec
  80.                       that you would like to use Fast memory if
  81.                       there is any, else use Chip memory, you
  82.                       should ask for MEMF_PUBLIC.
  83.  
  84.           If you want the allocated memory to be cleared
  85.           (initialized to zeros), you should set the flag
  86.           MEMF_CLEAR.
  87.  
  88. If you need to allocate 150 bytes of Chip memory, you would
  89. write:
  90.  
  91. /* Declare a pointer to the memory you are going to allocate: */
  92. CPTR memory; /* CPTR means memory pointer, declared in the    */
  93.              /* header file "exec/types.h". "exec/types.h" is */
  94.              /* automatically included when you include the   */
  95.              /* header file "intuition/intuition.h".          */
  96.  
  97. /* Allocate 150 bytes of Chip memory: */
  98. memory = (CPTR) AllocMem( 150, MEMF_CHIP );
  99.  
  100. /* Have we allocated the memory successfully? */
  101. if( memory == NULL )
  102.   /* ERROR! Have not allocated any memory! */
  103.  
  104.  
  105.  
  106. 9.2.2  DEALLOCATE MEMORY
  107.  
  108. All memory that has been allocated MUST be deallocated before
  109. your program terminates. If you forget to deallocate memory
  110. which you have allocated, that memory would be forever lost.
  111. The only way of freeing such memory is to reboot. (Not to be
  112. recommended. We are not Demo-writers, are we?)
  113.  
  114. You free allocated memory by calling the function FreeMem():
  115.  
  116. Synopsis: FreeMem( memory, size );
  117.  
  118. memory    (void *) Pointer to some memory which has previously
  119.           been allocated. Remember! Never deallocate memory,
  120.           which you have not allocated, and never use memory
  121.           which has been deallocated.
  122.  
  123. size      (long) The size (in bytes) of the memory you want to
  124.           deallocate.
  125.  
  126.  
  127. To deallocate the 150 bytes of Chip memory we have previously
  128. allocated, we write:
  129.  
  130. /* Free 150 bytes of memory: */
  131. FreeMem( memory, 150 );
  132.  
  133.  
  134.  
  135. 9.2.3  REMEMBER MEMORY
  136.  
  137. If you allocate memory several times, and in different
  138. quantities, it can be very hard to remember to deallocate all
  139. memory correctly. However, do not despair. Intuition have a
  140. solution for you. You can use the function AllocRemember()
  141. which calls the function AllocMem(), but will also allocate
  142. memory for a Remember structure which is automatically
  143. initialized for you. Every time you allocate memory with the
  144. AllocRemember() function, the Remember structures are linked
  145. together, and the information about the memory (size and
  146. position) is remembered. Once you want to deallocate the
  147. memory, you only need to call the function FreeRemember(), and
  148. all memory is deallocated for you automatically.
  149.  
  150. The Remember structure look like this:
  151.  
  152. struct Remember
  153. {
  154.   struct Remember *NextRemember;
  155.   ULONG RememberSize;
  156.   UBYTE *Memory;
  157. };
  158.  
  159.  
  160. The AllocRemember() function is called like this: (Very similar
  161. to the AllocMem() function.)
  162.  
  163. Synopsis: memory = AllocRemember( remember, size, type );
  164.  
  165. memory:   (char *) Pointer to the new allocated memory, or NULL
  166.           if no memory could be allocated. Remember! Never use
  167.           memory which you have not successfully allocated.
  168.  
  169. remember: (struct Remember **) Address of a pointer to a
  170.           Remember structure. Before you call the AllocRemember()
  171.           function for the first time you should set this
  172.           pointer to NULL. (Note that it is a pointer to a
  173.           pointer!)
  174.  
  175. size:     (long) The size (in bytes) of the memory you want.
  176.           (AllocMem() always allocates memory in multiples of
  177.           eight bytes. So if you only ask for 29 bytes, Exec
  178.           would actually give you 32 Bytes (4*8).)
  179.  
  180. type:     (long) You need to choose one of the three following
  181.           types of memory (see chapter 0 INTRODUCTION for more
  182.           information about Chip and Fast memory):
  183.  
  184.           MEMF_CHIP   Chip memory. This memory can be accessed
  185.                       by both the main processor, as well as
  186.                       the Chips. Graphics/Sound data MUST 
  187.                       therefore be placed in Chip memory. If it
  188.                       does not matter what type of memory you
  189.                       get (Fast or Chip), you should try to
  190.                       allocate Fast memory before you allocate
  191.                       Chip memory. (Chip memory is more valuable
  192.                       than Fast memory.)
  193.  
  194.           MEMF_FAST   Fast memory. This memory can only be
  195.                       accessed by the main processor. (Graphics
  196.                       and Sound data can NOT be stored in Fast
  197.                       memory, use Chip memory.) This memory is
  198.                       normally a little bit faster than Chip
  199.                       memory, since only the main processor is
  200.                       working with it, and it is not disturbed
  201.                       by the Chips.
  202.  
  203.           MEMF_PUBLIC If it does not matter what type of memory
  204.                       you get (you do not intend to use the
  205.                       memory for Graphic