mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-23 00:41:02 +00:00
New file.
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@2207 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Andrew McCallum
parent
3e2ce5f1fd
commit
6608b828a5
1 changed files with 632 additions and 0 deletions
632
Documentation/gnustep-zones.texi
Normal file
632
Documentation/gnustep-zones.texi
Normal file
|
|
@ -0,0 +1,632 @@
|
|||
\input texinfo @c -*- texinfo -*-
|
||||
@c %**start of header
|
||||
@setfilename gnustep-zones.info
|
||||
@settitle Memory Management in GNUstep
|
||||
@c %**end of header
|
||||
|
||||
@ifinfo
|
||||
@format
|
||||
START-INFO-DIR-ENTRY
|
||||
* GNUstep Zones: (gnustep-zones). Memory management in GNUstep.
|
||||
END-INFO-DIR-ENTRY
|
||||
@end format
|
||||
@end ifinfo
|
||||
|
||||
|
||||
@ifinfo
|
||||
This explains how to use dynamic memory allocation with the GNUstep base
|
||||
library.
|
||||
|
||||
Copyright (C) 1997 Yoo C. Chung and Free Software Foundation, Inc.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this
|
||||
manual provided the copyright notice and this permission notice are
|
||||
preserved on all copies.
|
||||
|
||||
@ignore
|
||||
Permission is granted to process this file through @TeX{} and print the
|
||||
results, provided the printed document carries copying permission notice
|
||||
identical to this one except for the removal of this paragraph (this
|
||||
paragraph not being relevant to the printed manual).
|
||||
@end ignore
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided also that the
|
||||
entire resulting derived work is distributed under the terms of a
|
||||
permission notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions.
|
||||
@end ifinfo
|
||||
|
||||
|
||||
@titlepage
|
||||
@title Memory Management in GNUstep
|
||||
@author Yoo C. Chung (wacko@@power1.snu.ac.kr)
|
||||
@page
|
||||
@vskip 0pt plus 1filll
|
||||
Copyright @copyright{} 1997 Yoo C. Chung and Free Software Foundation, Inc.
|
||||
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this
|
||||
manual provided the copyright notice and this permission notice are
|
||||
preserved on all copies.
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided also that the
|
||||
entire resulting derived work is distributed under the terms of a
|
||||
permission notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions.
|
||||
@end titlepage
|
||||
|
||||
|
||||
@c important TODO: Need examples!
|
||||
|
||||
|
||||
@ifinfo
|
||||
@node Top, Memory Management, (dir), (dir)
|
||||
@comment node-name, next, previous, up
|
||||
@top Memory Management in GNUstep
|
||||
|
||||
This explains how to use dynamic memory allocation when using the
|
||||
GNUstep Base Library.
|
||||
@end ifinfo
|
||||
|
||||
|
||||
@menu
|
||||
* Memory Management:: Dynamically allocating memory.
|
||||
* Concept Index:: Index of concepts.
|
||||
* Function Index:: Index of functions.
|
||||
* Data Type Index:: Index of data types.
|
||||
@end menu
|
||||
|
||||
|
||||
@node Memory Management, Concept Index, Top, Top
|
||||
@comment node-name, next, previous, up
|
||||
@chapter Memory Management
|
||||
@cindex Memory management
|
||||
|
||||
GNUstep uses zones for dynamic memory allocation.
|
||||
|
||||
@menu
|
||||
* Memory Management Concepts:: An introduction to concepts and terminology.
|
||||
* Introduction to Zones:: What are zones?
|
||||
* Creating Zones:: How to create zones.
|
||||
* Allocating Memory:: How to get memory from zones.
|
||||
* Resizing Memory:: How to resize memory within zones.
|
||||
* Freeing Memory:: Save memory by freeing unused memory.
|
||||
* Finding Zones:: Finding the zone that contains a chunk.
|
||||
* Recycling Zones:: When you don't need a zone anymore.
|
||||
* Naming Zones:: Zones have names.
|
||||
* Zone Customization:: Custom zones are possible.
|
||||
* Zone Consistency Checking:: Checking for errors.
|
||||
* Zone Statistics:: Obtaining statistics about a zone.
|
||||
* Zone Function Summary:: Summary of zone functions and structures.
|
||||
@end menu
|
||||
|
||||
|
||||
@node Memory Management Concepts, Introduction to Zones, Memory Management, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Memory Management Concepts
|
||||
@cindex Memory management concepts
|
||||
|
||||
A program does not always know how much memory it needs for its data (in
|
||||
fact, this is the case in most programs). One might statically allocate
|
||||
(this means that the amount of memory is determined at compile time)
|
||||
memory with some large size, but this can be either a huge waste or
|
||||
memory might run out. So memory must be allocated at runtime in these
|
||||
cases. This is called @dfn{dynamic memory allocation}.
|
||||
|
||||
Memory returned by a dynamic memory allocator is usually called a
|
||||
@dfn{memory block} or a @dfn{memory chunk}. Here we call them memory
|
||||
chunks.
|
||||
|
||||
@ignore
|
||||
We might give a better introduction here. But be careful not to give a
|
||||
long and boring one. Keep it simple! We might also give references to
|
||||
books where one can learn more about memory management.
|
||||
@end ignore
|
||||
|
||||
|
||||
@node Introduction to Zones, Creating Zones, Memory Management Concepts, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Introduction to Zones
|
||||
@cindex Zone introduction
|
||||
|
||||
Any reasonably complete C library will contain the functions
|
||||
@code{malloc} and @code{free}. One uses these functions for dynamic
|
||||
memory allocation in many C programs. These functions usually use all
|
||||
of the memory for potential allocation. This could result in two memory
|
||||
chunks being allocated far from each other in the virtual memory space,
|
||||
which could lead to increased paging.
|
||||
|
||||
Zones can be used to allocate many related memory chunks close to each
|
||||
other. A @dfn{zone} is an area (actually a set of areas) in memory
|
||||
where related chunks of memory can be allocated from. This might help
|
||||
in reducing paging on virtual memory systems. Each zone can have
|
||||
different behavior (@pxref{Zone Customization}).
|
||||
|
||||
The GNUstep Base Library uses zones for dynamic memory allocation. The
|
||||
functions that are used to obtain memory chunks from zones are thread
|
||||
safe.
|
||||
|
||||
@ignore
|
||||
Should give a more detailed and more understandable introduction. Might
|
||||
include a little history as well.
|
||||
@end ignore
|
||||
|
||||
|
||||
@node Creating Zones, Allocating Memory, Introduction to Zones, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Creating Zones
|
||||
@cindex Creating zones
|
||||
@cindex Default zone
|
||||
|
||||
In order to use a zone, it must first be created. You create zones with
|
||||
@code{NSCreateZone}, which is declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun NSZone* NSCreateZone (size_t @var{start}, size_t @var{gran}, BOOL @var{canFree})
|
||||
Creates a memory zone which starts with a size of at least @var{start}
|
||||
bytes and grows by at least @var{gran} bytes when needed. If
|
||||
@var{canFree} is @code{YES}, then memory chunks allocated in the zone
|
||||
can be freed. If @var{canFree} is @code{NO}, then memory chunks
|
||||
allocated in the zone cannot be freed unless the whole zone is recycled,
|
||||
nor can they be resized. A pointer pointing to the newly created zone
|
||||
is returned.
|
||||
|
||||
If @var{start} is zero, the zone will start out with some default size.
|
||||
If @var{gran} is zero, the zone will grow by some default number of
|
||||
bytes when the zone needs more memory.
|
||||
|
||||
If there isn't enough memory to create the zone, a
|
||||
@code{NSMallocException} is raised.
|
||||
@end deftypefun
|
||||
|
||||
We might want to use a zone that cannot free memory chunks in a
|
||||
situation where we need to allocate many chunks of memory and free them
|
||||
all at once after using them by recycling the zone (@pxref{Recycling
|
||||
Zones}), since a zone that cannot free memory chunks allocates memory
|
||||
faster than one that is able to free memory chunks. This is because a
|
||||
zone that cannot free memory chunks has a lot less bookkeeping to worry
|
||||
about.
|
||||
|
||||
You do not have to explicitly create a zone to dynamically allocate
|
||||
memory, since there already exists a default zone. A pointer to the
|
||||
default zone can be obtained with @code{NSDefaultMallocZone}, which is
|
||||
also declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun NSZone* NSDefaultMallocZone (void)
|
||||
Returns the default memory allocation zone. The default default zone
|
||||
cannot be recycled.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Allocating Memory, Resizing Memory, Creating Zones, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Allocating Memory Chunks
|
||||
@cindex Allocating memory chunks
|
||||
|
||||
In order to allocate a memory chunk from a zone, we need to use
|
||||
@code{NSZoneMalloc}, which is declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun {void*} NSZoneMalloc (NSZone *@var{zone}, size_t @var{size})
|
||||
Allocate @var{size} bytes from the zone pointed to by @var{zone}. A
|
||||
pointer to the allocated memory chunk is returned.
|
||||
|
||||
If @var{size} is zero @code{NULL} is returned. If there is not enough
|
||||
memory to allocate @var{size} bytes, a @code{NSMallocException} is
|
||||
raised.
|
||||
@end deftypefun
|
||||
|
||||
The contents of the allocated memory are uninitialized and
|
||||
unpredictable. We can allocate memory filled with zeroes with
|
||||
@code{NSZoneCalloc}, which is also declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun void* NSZoneCalloc (NSZone *@var{zone}, size_t @var{elems}, size_t @var{bytes})
|
||||
Allocate memory for @var{elems} elements (each of which are @var{bytes}
|
||||
bytes) from the zone pointed to by @var{zone}. The memory chunk is
|
||||
initialized with zeroes.
|
||||
|
||||
If either @var{elems} or @var{bytes} is zero, NULL is returned. If
|
||||
there is not enough memory for the request, a @code{NSMallocException}
|
||||
is raised.
|
||||
@end deftypefun
|
||||
|
||||
One should not depend on @code{NSZoneMalloc} and @code{NSZoneCalloc}
|
||||
returning @code{NULL} when the request size is zero. It's bad style,
|
||||
not to mention that this might change in the future, or might behave
|
||||
differently on custom zones (@pxref{Zone Customization}).
|
||||
|
||||
The zone containing a memory chunk allocated by @code{NSZoneMalloc} or
|
||||
@code{NSZoneCalloc} can be found with @code{NSZoneFromPointer}
|
||||
(@pxref{Finding Zones}).
|
||||
|
||||
|
||||
@node Resizing Memory, Freeing Memory, Allocating Memory, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Resizing Memory Chunks
|
||||
@cindex Resizing memory chunks
|
||||
|
||||
Sometimes one doesn't know how large a memory chunk one might need in
|
||||
advance. For example, if a memory chunk is a buffer for a line from a
|
||||
file, then no matter how large the buffer is, there might always be line
|
||||
that won't fit into the buffer.
|
||||
|
||||
@c The above example was stolen from the libc manual.
|
||||
|
||||
One can resize a memory chunk by using @code{NSZoneRealloc}, which is
|
||||
declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun void* NSZoneRealloc (NSZone *@var{zone}, void *@var{ptr}, size_t @var{size})
|
||||
Resizes the memory chunk pointed to by @var{ptr} to @var{size} bytes.
|
||||
If the memory chunk needs to be relocated, then the original contents
|
||||
will be copied to the new location. @var{ptr} may be @code{NULL}, in
|
||||
which case a new memory chunk will be allocated from the zone. The
|
||||
pointer to the resized memory chunk is returned.
|
||||
|
||||
If @var{size} is zero, the memory chunk pointed to by @var{ptr} is
|
||||
freed. If there is not enough memory to resize the chunk, a
|
||||
@code{NSMallocException} is raised.
|
||||
@end deftypefun
|
||||
|
||||
One shouldn't depend on @code{NSZoneRealloc} freeing the pointer with a
|
||||
size argument of zero or allocating a new chunk with a pointer argument
|
||||
of @code{NULL}, because it's bad style (in my humble opinion).
|
||||
|
||||
|
||||
@node Freeing Memory, Finding Zones, Resizing Memory, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Freeing Memory Chunks
|
||||
@cindex Freeing memory chunks
|
||||
|
||||
A memory chunk may no longer be needed after it is used. Then it would
|
||||
be better to free the memory chunk so it can be reused for other memory
|
||||
allocation requests. A memory chunk can be freed with
|
||||
@code{NSZoneFree}, which is declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun void NSZoneFree (NSZone *@var{zone}, void *@var{ptr})
|
||||
This frees the allocated memory chunk that @var{ptr} points at. The
|
||||
memory chunk must have been allocated from the zone pointed to by
|
||||
@var{zone}.
|
||||
@end deftypefun
|
||||
|
||||
Note that unlike the C library function @code{free}, calling
|
||||
@code{NSZoneFree} with a pointer argument of @code{NULL} is an error.
|
||||
|
||||
|
||||
@node Finding Zones, Recycling Zones, Freeing Memory, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Finding Zones Containing a Memory Chunk
|
||||
@cindex Finding zones
|
||||
|
||||
Sometimes one might need to find out the zone that contains a memory
|
||||
chunk. For example, objects derived from @code{NSObject} usually need
|
||||
to find out the zone it resides in to deallocate itself. One can find
|
||||
the zone with @code{NSZoneFromPointer}, which is declared in
|
||||
@file{NSZone.h}.
|
||||
|
||||
@deftypefun NSZone* NSZoneFromPointer (void *@var{ptr})
|
||||
Finds the zone that contains the memory chunk pointed to by @var{ptr}
|
||||
and returns a pointer to it. @var{ptr} must be a pointer returned by
|
||||
@code{NSZoneMalloc} or @code{NSZoneRealloc}.
|
||||
@end deftypefun
|
||||
|
||||
@code{NSZoneFromPointer} takes a constant amount of time regardless of
|
||||
how many zones or memory chunks there are, so it would save space to use
|
||||
@code{NSZoneFromPointer} instead of saving the zone separately.
|
||||
|
||||
|
||||
@node Recycling Zones, Naming Zones, Finding Zones, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Recycling Zones
|
||||
@cindex Recycling zones
|
||||
|
||||
A zone can become useless after a while. Then it would be better to
|
||||
recycle the zone to save memory. This can be done with
|
||||
@code{NSRecycleZone}, which is declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun void NSRecycleZone (NSZone *@var{zone})
|
||||
This function recycles the zone. All memory in the zone will be
|
||||
reclaimed.
|
||||
@end deftypefun
|
||||
|
||||
Note that when a zone in GNUstep are recycled, all memory in the zone
|
||||
will be recycled, unlike zones in the Foundation Kit of OpenStep, where
|
||||
zones that can free memory return live objects to the default zone.
|
||||
|
||||
|
||||
@node Naming Zones, Zone Customization, Recycling Zones, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Naming Zones
|
||||
@cindex Naming zones
|
||||
@cindex Zone names
|
||||
|
||||
Memory allocation zones can be named. You might want to do this as a
|
||||
debugging aid. You can set the name of a zone with @code{NSSetZoneName}
|
||||
and obtain the name of a zone with @code{NSZoneName}, which are declared
|
||||
in @file{NSZone.h}.
|
||||
|
||||
@deftypefun void NSSetZoneName (NSZone *@var{zone}, NSString *@var{name})
|
||||
This sets a name for the zone pointed to by @var{zone}. If @var{name}
|
||||
is @code{nil}, the name of the zone will be unset if there was a name
|
||||
previously set. Otherwise a copy will be made of @var{name} in the
|
||||
default zone, and the name of the zone will be set to the copy.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun NSString* NSZoneName (NSZone *@var{zone})
|
||||
Returns the name for the zone pointed to by @var{zone}. Don't release
|
||||
it unless you have retained it.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Zone Customization, Zone Consistency Checking, Naming Zones, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Customization
|
||||
@cindex Customizing zones
|
||||
|
||||
The behavior of memory allocation zones can be customized in GNUstep,
|
||||
unlike zones with the Foundation Kit of OpenStep, which has a fixed
|
||||
default zone and only two kinds of zones possible.
|
||||
|
||||
@menu
|
||||
* Setting Default Zone:: The default zone can be changed.
|
||||
* Creating Custom Zones:: Zones with customized behavior can be created.
|
||||
@end menu
|
||||
|
||||
|
||||
@node Setting Default Zone, Creating Custom Zones, Zone Customization, Zone Customization
|
||||
@comment node-name, next, previous, up
|
||||
@subsection Setting the Default Zone
|
||||
@cindex Setting default zone
|
||||
|
||||
Initially there is a default default zone. But the performance of the
|
||||
default allocator might not be satisfactory for a program. In such
|
||||
cases, you may want to change the default zone to a zone that has more
|
||||
satisfactory performance. You can do this with
|
||||
@code{NSSetDefaultMallocZone}, which is declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun void NSSetDefaultMallocZone (NSZone *@var{zone})
|
||||
This sets the default memory allocation zone to the zone pointed to by
|
||||
@var{zone}.
|
||||
@end deftypefun
|
||||
|
||||
You shouldn't change the default zone unless you know what you're doing.
|
||||
|
||||
Note that @code{NSSetDefaultMallocZone} is not defined by OpenStep.
|
||||
|
||||
|
||||
@node Creating Custom Zones, , Setting Default Zone, Zone Customization
|
||||
@comment node-name, next, previous, up
|
||||
@subsection Creating Custom Zones
|
||||
@cindex Creating a custom zone
|
||||
@tindex struct _NSZone
|
||||
|
||||
A zone with a custom behavior and implementation can be created. For
|
||||
example, all memory chunks allocated within a zone may have the same
|
||||
size, in which case a much more simpler allocator than the default one
|
||||
can be used.
|
||||
|
||||
A custom zone can be created by appropriately setting the members of the
|
||||
structure @code{NSZone} (actually this is a typedef to @code{struct
|
||||
_NSZone}), which is declared in @file{NSZone.h}.
|
||||
|
||||
@deftp {Data Type} NSZone
|
||||
This is actually a typedef to @code{struct _NSZone}. This structure
|
||||
contains the following members, all of which must be set to be properly
|
||||
used as a zone.
|
||||
|
||||
@table @code
|
||||
|
||||
@item void *(*malloc)(NSZone *@var{zone}, size_t @var{size})
|
||||
This is a pointer to the function that allocates @var{size} bytes from
|
||||
the zone pointed to by @var{zone}. (@pxref{Allocating Memory})
|
||||
|
||||
@item void *(*realloc)(NSZone *@var{zone}, void *@var{ptr}, size_t @var{size})
|
||||
This is a pointer to the function that resizes the memory chunk pointed
|
||||
to by @var{ptr}, which was allocated from the zone pointed to by
|
||||
@var{zone}, to @var{size} bytes. (@pxref{Resizing Memory})
|
||||
|
||||
@item void (*free)(NSZone *@var{zone}, void *@var{ptr})
|
||||
This is a pointer to the function that returns the memory chunk pointed
|
||||
to be @var{ptr} to the zone pointed to by @var{zone}. (@pxref{Freeing
|
||||
Memory})
|
||||
|
||||
@item void (*recycle)(NSZone *@var{zone})
|
||||
This is a pointer to the function that recycles the zone pointed to by
|
||||
@var{zone}. (@pxref{Recycling Zones})
|
||||
|
||||
@item BOOL (*check)(NSZone *@var{zone})
|
||||
This is a pointer to the function that checks the integrity of the zone
|
||||
that is pointed to by @var{zone}. (@pxref{Zone Consistency Checking})
|
||||
|
||||
@item struct NSZoneStats (*stats)(NSZone *@var{zone})
|
||||
This is a pointer to the function that returns statistics about the zone
|
||||
pointed to by @var{zone}. (@pxref{Zone Statistics})
|
||||
|
||||
@item size_t gran
|
||||
This holds the granularity of the zone. (@pxref{Creating Zones})
|
||||
|
||||
@item NSString *name
|
||||
This points to the name of the zone. (@pxref{Naming Zones})
|
||||
|
||||
@end table
|
||||
|
||||
@end deftp
|
||||
|
||||
To create the functions that a zone uses, you'll probably have to use
|
||||
@code{NSZoneRegisterChunk} and @code{NSZoneChunkOverhead}, which are
|
||||
also declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun void* NSZoneRegisterChunk (NSZone *@var{zone}, void *@var{chunk})
|
||||
This registers the memory chunk pointed to by @var{chunk} so that
|
||||
@code{NSZoneFromPointer} will work (@pxref{Finding Zones}). A pointer
|
||||
to the beginning of the memory that should actually be returned to the
|
||||
user is returned.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun size_t NSZoneChunkOverhead (void)
|
||||
This returns the overhead that is needed for @code{NSZoneFromPointer}
|
||||
(@pxref{Finding Zones}) to work in bytes.
|
||||
@end deftypefun
|
||||
|
||||
Creating a custom zone could be an error prone process, so don't use
|
||||
them unless you know what you're doing (and willing to go through a
|
||||
potentially long debugging process).
|
||||
|
||||
Note that @code{NSZoneRegisterChunk} and @code{NSZoneChunkOverhead} are
|
||||
not defined in OpenStep.
|
||||
|
||||
|
||||
@node Zone Consistency Checking, Zone Statistics, Zone Customization, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Zone Consistency Checking
|
||||
@cindex Checking consistency of a zone
|
||||
|
||||
You can check the integrity of a zone by using @code{NSZoneCheck}, which
|
||||
is declared in @file{NSZone.h}.
|
||||
|
||||
@deftypefun BOOL NSZoneCheck (NSZone *@var{zone})
|
||||
Checks the integrity of the zone pointed to by @var{zone}. Returns
|
||||
@code{YES} if there are no errors, returns @code{NO} otherwise.
|
||||
@end deftypefun
|
||||
|
||||
Note that @code{NSZoneCheck} is not defined in OpenStep.
|
||||
|
||||
|
||||
@node Zone Statistics, Zone Function Summary, Zone Consistency Checking, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Zone Statistics
|
||||
@cindex Zone statistics
|
||||
|
||||
You can obtain statistics about a zone with @code{NSZoneStats} which
|
||||
returns the statistics in a @code{struct NSZoneStats}. These are
|
||||
declared in @file{NSZone.h}.
|
||||
|
||||
@deftp {Data Type} {struct NSZoneStats}
|
||||
|
||||
This structure type is used to return statistics about a zone, and has
|
||||
the following members:
|
||||
|
||||
@table @code
|
||||
|
||||
@item size_t bytes_total
|
||||
This is the total size of memory managed by the zone, in bytes.
|
||||
|
||||
@item size_t chunks_used
|
||||
This is the number of memory chunks in use in the zone.
|
||||
|
||||
@item size_t bytes_used
|
||||
This is the number of bytes in use.
|
||||
|
||||
@item size_t chunks_free
|
||||
This is the number of memory chunks that are not in use.
|
||||
|
||||
@item size_t bytes_free
|
||||
This is the number of bytes managed by the zone that are not in use.
|
||||
|
||||
@end table
|
||||
|
||||
@end deftp
|
||||
|
||||
@deftypefun {struct NSZoneStats} NSZoneStats (NSZone *@var{zone})
|
||||
This returns statistics about the zone pointed to by @var{zone} in a
|
||||
structure of type @code{struct NSZoneStats}.
|
||||
@end deftypefun
|
||||
|
||||
Note that @code{NSZoneStats} (and obviously @code{struct NSZoneStats})
|
||||
is not defined in OpenStep.
|
||||
|
||||
|
||||
@node Zone Function Summary, , Zone Statistics, Memory Management
|
||||
@comment node-name, next, previous, up
|
||||
@section Summary
|
||||
|
||||
Here is a summary of the functions and data types that work with memory
|
||||
allocation zones, which are all declared in @file{NSZone.h}:
|
||||
|
||||
@table @code
|
||||
|
||||
@item NSZone* NSCreateZone (size_t @var{start}, size_t @var{gran}, BOOL @var{canFree})
|
||||
Creates a zone. (@pxref{Creating Zones})
|
||||
|
||||
@item NSZone* NSDefaultMallocZone (void)
|
||||
Returns the default zone. (@pxref{Creating Zones})
|
||||
|
||||
@item void* NSZoneMalloc (NSZone *@var{zone}, size_t @var{size})
|
||||
Allocates memory from a zone. (@pxref{Allocating Memory})
|
||||
|
||||
@item void* NSZoneCalloc (NSZone *@var{zone}, size_t @var{elems}, size_t @var{bytes})
|
||||
Allocates memory initialized with zeroes from a zone.
|
||||
(@pxref{Allocating Memory})
|
||||
|
||||
@item void* NSZoneRealloc (NSZone *@var{zone}, void *@var{ptr}, size_t @var{size})
|
||||
Resizes a memory chunk that had been allocated from a zone.
|
||||
(@pxref{Resizing Memory})
|
||||
|
||||
@item void NSZoneFree (NSZone *@var{zone}, void *@var{ptr})
|
||||
Returns a memory chunk to the zone. (@pxref{Freeing Memory})
|
||||
|
||||
@item NSZone* NSZoneFromPointer (void *@var{ptr})
|
||||
Finds the zone that contains a memory chunk. (@pxref{Finding Zones})
|
||||
|
||||
@item void NSRecycleZone (NSZone *@var{zone})
|
||||
Recycles a zone. (@pxref{Recycling Zones})
|
||||
|
||||
@item void NSSetZoneName (NSZone *@var{zone}, NSString *@var{name})
|
||||
Sets a name for a zone. (@pxref{Naming Zones})
|
||||
|
||||
@item NSString* NSZoneName (NSZone *@var{zone})
|
||||
Returns the name for a zone. (@pxref{Naming Zones})
|
||||
|
||||
@item void NSSetDefaultMallocZone (NSZone *@var{zone})
|
||||
Set the default zone. (@pxref{Setting Default Zone})
|
||||
|
||||
@item void* NSZoneRegisterChunk (NSZone *@var{zone}, void *@var{chunk})
|
||||
Function used in custom zones to register a memory chunk.
|
||||
(@pxref{Creating Custom Zones})
|
||||
|
||||
@item void* NSZoneChunkOverhead (void)
|
||||
Function used in custom zones to find overhead for each memory chunk.
|
||||
(@pxref{Creating Custom Zones})
|
||||
|
||||
@item BOOL NSZoneCheck (NSZone *@var{zone})
|
||||
Checks the integrity of a zone. (@pxref{Zone Consistency Checking})
|
||||
|
||||
@item struct NSZoneStats NSZoneStats (NSZone *@var{zone})
|
||||
Returns statistics about a zone. (@pxref{Zone Statistics})
|
||||
|
||||
@item NSZone
|
||||
Typedef to @code{struct _NSZone}, which is a structure type that
|
||||
actually holds the zone. (@pxref{Creating Custom Zones})
|
||||
|
||||
@item struct NSZoneStats
|
||||
Structure type used to return statistics about a zone. (@pxref{Zone
|
||||
Statistics})
|
||||
|
||||
@end table
|
||||
|
||||
|
||||
@node Concept Index, Function Index, Memory Management, Top
|
||||
@comment node-name, next, previous, up
|
||||
@unnumbered Concept Index
|
||||
|
||||
@printindex cp
|
||||
|
||||
|
||||
@node Function Index, Data Type Index, Concept Index, Top
|
||||
@comment node-name, next, previous, up
|
||||
@unnumbered Function Index
|
||||
|
||||
@printindex fn
|
||||
|
||||
|
||||
@node Data Type Index, , Function Index, Top
|
||||
@comment node-name, next, previous, up
|
||||
@unnumbered Data Type Index
|
||||
|
||||
@printindex tp
|
||||
|
||||
|
||||
@bye
|
||||
Loading…
Reference in a new issue