Return to gcalloc.3r CVS log

Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3

Annotation of researchv10dc/630/man/src/p_man/man3/gcalloc.3r, revision 1.1

1.1     ! root        1: .ds ZZ DEVELOPMENT PACKAGE
        !             2: .TH GCALLOC 3R "630 MTG"
        !             3: .XE "gcalloc()"
        !             4: .XE "gcallocown()"
        !             5: .XE "gcfree()"
        !             6: .SH NAME
        !             7: gcalloc, gcfree, gcallocown \- garbage compacting memory allocation
        !             8: .SH SYNOPSIS
        !             9: .B #include <dmd.h>
        !            10: .sp
        !            11: .B char \(**gcalloc (nbytes, where)
        !            12: .PP
        !            13: .B void gcfree (s)
        !            14: .PP
        !            15: .B void gcallocown (s, p)
        !            16: .PP
        !            17: .B unsigned long nbytes;
        !            18: .br
        !            19: .B long \(**\(**where;
        !            20: .br
        !            21: .B char \(**s;
        !            22: .br
        !            23: .B Proc \(**p;
        !            24: .SH DESCRIPTION
        !            25: The
        !            26: .I gcalloc
        !            27: function
        !            28: provides a simple garbage-compacting memory allocator.
        !            29: It returns either a pointer to a block of
        !            30: .I nbytes
        !            31: contiguous bytes of storage or a \s-1NULL\s+1 if unavailable.
        !            32: The storage is not initialized to zeros.
        !            33: The pointer
        !            34: .I where
        !            35: points to the location where the address of the
        !            36: storage block is to be saved.
        !            37: The contents of
        !            38: .I where
        !            39: will be updated after each compaction.
        !            40: That is, if garbage collection occurs, your storage will be moved,
        !            41: and your pointer will be changed to point to the new location of your
        !            42: storage area.
        !            43: Therefore, a program using
        !            44: .I gcalloc
        !            45: should never store the location of 
        !            46: gcallocated
        !            47: memory anywhere other than the location handed to the allocator.
        !            48: Typically, this location is contained in a structure such as a \fIBitmap\fR.
        !            49: .PP
        !            50: The
        !            51: .I gcallocown
        !            52: function
        !            53: changes the owning process of the memory returned by
        !            54: .IR gcalloc .
        !            55: If
        !            56: .I p
        !            57: is zero, the memory will belong to no one and will only be freed by an explicit call to
        !            58: .IR gcfree .
        !            59: .PP
        !            60: The
        !            61: .I gcfree
        !            62: function
        !            63: frees the storage block at
        !            64: \fIs\fR,
        !            65: thus making it available for future allocation.
        !            66: .PP
        !            67: The terminal
        !            68: automatically frees all memory \fIgcalloc\fR'ed and owned by a process
        !            69: when the process terminates or when
        !            70: the window it is running in is deleted.
        !            71: However, it is recommended that a process free its garbage compactable
        !            72: memory when the storage is no longer needed so that other
        !            73: processes
        !            74: will be able to use it.
        !            75: 
        !            76: .SH EXAMPLE
        !            77: These routines could be used for allocating and freeing space
        !            78: used to store Points in a polygon.
        !            79: .PP
        !            80: .RS 3
        !            81: .ft CM
        !            82: .S -2
        !            83: .nf
        !            84: #include <dmd.h>
        !            85: 
        !            86: Point *poly;
        !            87: 
        !            88: Point *
        !            89: polyalloc(n)
        !            90: {
        !            91:      char *gcalloc();
        !            92: 
        !            93: return (poly = (Point *)gcalloc(sizeof(Point)*n, &poly));
        !            94: }
        !            95: 
        !            96: polyfree( )
        !            97: {
        !            98:      void gcfree();
        !            99: 
        !           100:      gcfree (poly);
        !           101: }
        !           102: .fi
        !           103: .ft R
        !           104: .S +2
        !           105: .SH SEE ALSO
        !           106: alloc(3R), balloc(3R), structures(3R).
        !           107: 
        !           108: .SH DIAGNOSTICS
        !           109: When garbage compaction is in effect, a small rectangle flashes on the
        !           110: upper left corner of the terminal's screen.
        !           111: .SH BUGS
        !           112: If \f2gcalloc\f1 is called to attempt to allocate over 7000000
        !           113: bytes, it will fail, but it may say it succeeded. If this
        !           114: happens, the memory used by \f2gcalloc\f1 is corrupted and may
        !           115: damage other programs running in the terminal.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.