Name

Zone -- modular unit of storage allocation

Synopsis

//
// Zone -- modular unit of storage allocation
//
@deftype Zone 
CREATING
- (void)	setObjectCollection: (BOOL)objectCollection;
- (void)	setPageSize: (int)pageSize;
USING
- (BOOL)	getObjectCollection;
- (int)		getPageSize;

-		allocIVars: aClass;
-		copyIVars: anObject;
- (void)	freeIVars: anObject;

-               getObjects;

- (void *)	alloc: (size_t)size;
- (void)	free: (void *)aBlock;

- (void *)	allocBlock: (size_t)size;
- (void *)	copyBlock: (void *)aBlock blockSize: (size_t)size;
- (void)	freeBlock: (void *)aBlock blockSize: (size_t)size;

-		createAllocSize: (size_t)size;

-		getSubzones;
- (void)	mergeWithOwner;

- (BOOL)	isSubzoneAlloc: (void *)pointer;
-		getAllocSubzone: (void *)pointer;
@end

@deftype AllocSize 
- (int)		getAllocSize;
/*
Inline functions for use of AllocSize objects:
   void  *allocSize( AllocSize *anAllocSize );
   void  *freeSize(  AllocSize *anAllocSize, void *aBlock );
*/
@end

Description

Zones also provide an optional service to maintain a collection of all objects allocated within the zone. This collection is a set of all objects which have been created but not yet dropped within the zone. Collections maintained automatically by zones can eliminate a need for other, separately maintained collections in applications that need to keep track of entire populations of objects. Collections of allocated objects can provide support for object query, external object storage, and automatic storage reclamation.

A zone may be used to obtain storage not only for objects, but also for raw storage blocks like those provided by the C malloc function. All objects and storage blocks allocated in a zone remain local to that zone. This means that allocation of storage in other zones does not affect the efficiency of storage allocation within a particular zone. For most zone types, individual allocations may still be freed within a zone, and total storage of a zone may grow and shrink according to aggregate needs. In addition to freeing individual allocations, an entire zone may also dropped. Dropping a zone automatically frees all allocations made within it, including final drop processing on any allocated objects that need it. Release of an entire zone can be much faster than individual release of each object within it.

The Zone type is a fully implemented type that provides default storage management support for objects and other allocated storage. It is also a supertype for other zones that implement alternative policies for use in specialized situations.

(..No Zone subtypes have been written yet. The current Zone implementation is a temporary one based on a simple pass-through of all allocation requests to the C library malloc function. Considerable improvements in storage allocation are possible when this current crude implementation is replaced by more efficient allocation local to each zone. Future zone types will also support automatic garbage collection..)

Inherited behavior

@deftype Zone 

Since a new zone always requires that an existing zone be identified, no new zones could be created unless there were some zones that already existed. Several such zones are predefined as part of the defobj library; see predefined zones for a summary.

Create-time behavior

ObjectCollection

PageSize

Object allocation

-		allocIVars: aClass;
-		copyIVars: anObject;
- (void)	freeIVars: anObject;

-               getObjects;

copyIVars: creates copies an existing instance variable structure into a new allocation made within the local zone. The existing instance variable structure may be in any zone, but must contain a class pointer in its first word that correctly describes the size of the structure.

freeIVars: releases storage that was previously allocated to hold the instance variable structure of an object. The first word of the object must be a class pointer that correctly describes the size of the structure. Storage allocated by allocIVars: or copyIVars: may be freed only by freeIVars:, and freeIVars: may be used only to free storage allocated by one of these messages.

getObjects returns a collection all objects allocated in a zone using either allocIVars: or copyIVars: and not yet freed using freeIVars:. getObjects returns nil if the ObjectCollection option is false. The collection returned has the type OrderedSet as defined in the collections library, with the ReadOnly option set true and the IndexSafety option set to SafeAlways. The members of this collection may change as objects are allocated and freed, but may not added or removed directly within the collection.

The object allocation functions are intended for use only within the implementation of an object class. Users of an object type should create a new object only using create: messages or other messages provided for this purpose.

Raw storage block allocation

- (void *)	alloc: (size_t)size;
- (void)	free: (void *)aBlock;

- (void *)	allocBlock: (size_t)size;
- (void *)	copyBlock: (void *)aBlock blockSize: (size_t)size;
- (void)	freeBlock: (void *)aBlock blockSize: (size_t)size;

-		createAllocSize: (size_t)size;

free: releases a block of storage previously allocated using alloc:. The size of the block is not required as an argument because alloc: has saved this size as necessary as part of the initial allocation. free: may be used only to free a block allocated by alloc:, and a block allocated by alloc: may be freed only by free:.

allocBlock: allocates a new storage block similar to alloc:, except that the size of the block allocated must be passed as an argument when freeing the block. copyBlock:blockSize: allocates a new storage with the same requirements on free as allocBlock:, but also fills the new storage with the contents of a block passed as the first argument, up to the size of the newly allocated block. freeBlock:blockSize: must be used to free any block previously allocated by allocBlock: or copyBlock:blockSize.

createAllocSize: returns a new object that supports the most efficient allocation available on blocks that all have the same size. It provides a low-level storage allocation mechanism that would typically be used only to build and maintain data structures made up of many small blocks of uniform size.

The size of blocks to be allocated by a particular AllocSize object is passed as the argument to createAllocSize:. AllocSize is a defined type for objects returned by createAllocSize:, and inherits standard messages from both DefinedObject and Drop. An AllocSize object cannot be created in any way other than as a return value from createAllocSize:.

Following is the one message defined by the AllocSize type:

- (int)		getAllocSize;

void  *allocSize( AllocSize *anAllocSize );
void  *freeSize(  AllocSize *anAllocSize, void *aBlock );

Subzone structure

-		getSubzones;
- (void)	mergeWithOwner;

- (BOOL)	isSubzoneAlloc: (void *)pointer;
-		getAllocSubzone: (void *)pointer;

isSubzoneAlloc: tests if a particular allocation was made by the local zone, or any zone which obtains storage from that zone. The pointer argument must point to an allocation previously made by any zone. The message returns true if the allocation was made by either the local zone or any of its subzones. getAllocSubzone is similar, except that it returns the particular zone in which the pointer was allocated, or nil if the pointer was not allocated in the local zone or one of its subzones. (..neither message currently implemented..)