mirror of
https://github.com/gnustep/libs-base.git
synced 2025-05-29 16:01:38 +00:00
f3b19ddb8d
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@2204 72102866-910b-0410-8b05-ffd578937521
125 lines
4.1 KiB
Text
125 lines
4.1 KiB
Text
\input texinfo @c -*- texinfo -*-
|
|
@c %**start of header
|
|
@setfilename NSZone.info
|
|
@settitle Zone Functions in GNUstep
|
|
@c %**end of header
|
|
|
|
@ifinfo
|
|
This explains the zone functions in the GNUstep base library.
|
|
|
|
This document is in the public domain.
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title Zone Funtions in GNUstep
|
|
@author Yoo C. Chung
|
|
@end titlepage
|
|
|
|
|
|
@node Top, (dir), (dir), (dir)
|
|
@comment node-name, next, previous, up
|
|
|
|
@ifinfo
|
|
This explains how to use the zone functions in the GNUstep base library.
|
|
@end ifinfo
|
|
|
|
For the current implementation, memory allocated by @code{malloc()}
|
|
cannot be freed by @code{NSZoneFree()}, and memory allocated by
|
|
@code{NSZoneMalloc()} cannot be freed by @code{free()}.
|
|
|
|
All the zone functions should be thread safe, though you should still be
|
|
careful (it wouldn't make much sense to use a zone before it's created
|
|
or after it's recycled).
|
|
|
|
|
|
@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 allocated in the zone can be
|
|
freed. If @var{canFree} is @code{NO}, then memory allocated in the zone
|
|
cannot be freed unless the whole zone is recycled (in which case the
|
|
memory will be returned to the system regardless of whether they are
|
|
still in use).
|
|
|
|
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.
|
|
|
|
There is no advantage in setting @var{start} or @var{gran} to a multiple
|
|
of the page size of the machine.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {NSZone *} NSDefaultMallocZone (void)
|
|
Returns the default memory zone.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {NSZone *} NSZoneFromPointer(void *@var{ptr})
|
|
Finds the zone that contains the memory pointed to by @var{ptr}. This
|
|
should be very fast.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void NSRecycleZone (NSZone *@var{zone})
|
|
This function destroys the zone. If @var{zone} is a zone that can free
|
|
allocated memory, then memory blocks in the zone that are still in use
|
|
will be merged with the default zone (or at least they should be, they
|
|
currently aren't merged). If not, all memory in the zone will be
|
|
reclaimed.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {void *} NSZoneMalloc (NSZone *@var{zone}, size_t @var{size})
|
|
Allocate @var{size} bytes from @var{zone} and return a pointer to the
|
|
allocated memory.
|
|
|
|
If @var{size} is zero @code{NULL} is returned.
|
|
@end deftypefun
|
|
|
|
|
|
@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 @var{zone}. The memory is initialized with zeroes.
|
|
|
|
If either @var{elems} or @var{bytes} is zero, NULL is returned.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {void *} NSZoneRealloc (NSZone *@var{zone}, void *@var{ptr}, size_t @var{size})
|
|
Resizes the memory block pointed to by @var{ptr} to @var{size} bytes.
|
|
If the memory block 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 block will be allocated from the zone.
|
|
|
|
If @var{size} is zero, the memory pointed to by @var{ptr} is freed.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void NSZoneFree (NSZone *@var{zone}, void *@var{ptr})
|
|
This frees the allocated memory that @var{ptr} points at. The memory
|
|
block must have been allocated from the @var{zone}.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void NSSetZoneName (NSZone *@var{zone}, NSString *@var{name})
|
|
This sets a name for @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.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {NSString *} NSZoneName (NSZone *@var{zone})
|
|
Returns the name for @var{zone}. Don't release it!
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun {BOOL} NSZoneInUse (void *@var{ptr})
|
|
Returns whether @var{ptr} points to memory that has been allocated or not.
|
|
It does not work for memory allocated from a zone that cannot free memory.
|
|
|
|
This function is not in OpenStep.
|
|
@end deftypefun
|
|
|
|
|
|
@bye
|