.\" $Id: memcluster.mdoc,v 1.1.2.1.10.1 2004/03/09 08:33:43 marka Exp $.\".\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC").\" Copyright (c) 1995-1999 by Internet Software Consortium.\".\" Permission to use, copy, modify, and distribute this software for any.\" purpose with or without fee is hereby granted, provided that the above.\" copyright notice and this permission notice appear in all copies..\".\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE..\".\" The following six UNCOMMENTED lines are required..Dd Month day, year.\"Os OPERATING_SYSTEM [version/release].Os BSD 4.\"Dt DOCUMENT_TITLE [section number] [volume].Dt MEMCLUSTER 3.Sh NAME.Nm meminit ,.Nm memget ,.Nm memput ,.Nm memstats .Nd memory allocation/deallocation system.Sh SYNOPSIS.Fd #include \&<isc/memcluster.h\&>.Ft void * .Fn memget "size_t size".Ft void .Fn memput "void *mem" "size_t size".Ft void .Fn memstats "FILE *out".Sh DESCRIPTIONThese functions access a memory management system which allows callers to not fragment memory to the extent which can ordinarily occur through many random calls to.Xr malloc 3 .Instead, .Fn memgetgets a large contiguous chunk of blocks of the requested .Fa size and parcels out these blocks as requested.  The symmetric call is.Fn memput ,which callers use to return a piece of memory obtained from.Fn memget .Statistics about memory usage are returned by.Fn memstats , which prints a report on the stream.Fa out ..Ss INTERNALSInternally, linked lists of free memory blocks are stored in an array.The size of this array is determined by the value.Dv MEM_FREECOUNT ,currently set to 1100.  In general, for any requested blocksize.Dq Fa size ,any free blocks will be stored on the linked list at that index.No free lists are managed for blocks greater than or equal to.Dv MEM_FREECOUNTbytes; instead, calls to.Xr malloc 3or.Xr free 3are made, directly..PpSince the blocks are actually stored as linked lists, they must at leastbe large enough to hold a pointer to the next block.  This size, which is.Dv SMALL_SIZE_LIMIT ,is currently defined as.Bd -literal -offset indent#define SMALL_SIZE_LIMIT sizeof(struct { void *next; }).Ed.PpBoth .Fn memgetand.Fn memputenforce this limit; for example, any call to .Fn memget requesting a block smaller than.Dv SMALL_SIZE_LIMITbytes will actually be considered to be of size.Dv SMALL_SIZE_LIMIT internally.  (Such a caller request will be logged for .Fn memstatspurposes using the caller-requested.Fa size ;see the discussion of.Fn memstats ,below, for more information.).PpAdditionally, the requested.Fa sizewill be adjusted so that when a large .Xr malloc 3 Ns No -dchunk of memory is broken up into a linked list, the blocks will all fall onthe correct memory alignment boundaries.  Thus, one can conceptualize a callwhich mentions.Fa sizeas resulting in a.Fa new_sizewhich is used internally..PpIn order to more efficiently allocate memory, there is a .Dq targetsize for calls to .Xr malloc 3 .It is given by the pre-defined value.Dv MEM_TARGET , which is currently 4096 bytes.For any requested block.Fa size ,enough memory is .Xr malloc 3 Ns No -din order to fill up a block of about.Dv MEM_TARGETbytes.  .No [ Ns Sy NOTE :For allocations larger than.Dv MEM_TARGET Ns No /2bytes, there is a .Dq fudge factorintroduced which boosts the target size by 25% of.Dv MEM_TARGET .This means that enough memory for two blockswill actually be allocated for any .Fa sizesuch that.Pq Dv MEM_TARGET Ns No / 3 .No < Fa size No < .Pq Dv MEM_TARGET Ns No *5/8 ,provided that the value of.Dv MEM_FREECOUNT is at least as large as the upper limit shown above.].Pp.Ss FUNCTION DESCRIPTIONS.PpThe function.Fn memgetreturns a pointer to a block of memory of at least the requested.Fa size .After adjusting.Fa sizeto the value.Va new_sizeas mentioned above in the .Sx INTERNALSsubsection, the internal array of free lists is checked.If there is no block of the needed.Va new_size ,then.Fn memget will .Xr malloc 3a chunk of memory which is as many times as .Va new_sizewill fit into the target size.  This memory is then turned into a linked list of .Va new_size Ns No -sizedblocks which are given out as requested; the last such block is the first one returned by .Fn memget .If the requested.Fa sizeis zero or negative, then .Dv NULLis returned and.Va errnois set to.Dv EINVAL ;if .Fa sizeis larger than or equal to the pre-defined maximum size.Dv MEM_FREECOUNT ,then only a single block of exactly .Fa sizewill be.Xr malloc 3 Ns No -dand returned..PpThe.Fn memputcall is used to return memory once the caller is finished with it.After adjusting.Fa sizethe the value.Va new_sizeas mentioned in the .Sx INTERNALS subsection, above, the block is placed at the head of the free list of .Va new_size Ns -sizedblocks.If the given.Fa sizeis zero or negative, then .Va errnois set to.Dv EINVAL ,as for.Fn memget .If .Fa sizeis larger than or equal to the pre-defined maximum size.Dv MEM_FREECOUNT ,then the block is immediately.Xr free 3 Ns No -d ..Pp.Sy NOTE :It is important that callers give .Fn memput.Em onlyblocks of memory which were previously obtained from.Fn memget if the block is .Em actually less than.Dv SMALL_SIZE_LIMITbytes in size.  Since all blocks will be added to a free list, any block which is not at least.Dv SMALL_SIZE_LIMITbytes long will not be able to hold a pointer to the next block in thefree list..PpThe.Fn memstatsfunction will summarize the number of calls to .Fn memgetand.Fn memputfor any block size from 1 byte up to.Pq Dv MEM_FREECOUNT No - 1  bytes, followed by a single line for any calls using a .Fa sizegreater than or equal to .Dv MEM_FREECOUNT ; a brief header with shell-style comment lines prefaces the report andexplains the information.  The .Dv FILE pointer.Fa outidentifies the stream which is used for this report.  Currently, .Fn memstatreports the number of calls to .Fn memgetand.Fn memputusing the caller-supplied value .Fa size ; the percentage of outstanding blocks of a given size (i.e., the percentageby which calls to.Fn memgetexceed .Fn memput )are also reported on the line for blocks of the given.Fa size .However, the percent of blocks used is computed using the number of blocks allocated according to the internal parameter.Va new_size ;it is the percentage of blocks used to those available at a given.Va new_size ,and is computed using the.Em totalnumber of caller .Dq getsfor any caller.Fa size Ns No -swhich map to the internally-computed.Va new_size .Keep in mind that.Va new_sizeis generally .Em notequal to.Fa size , which has these implications:.Bl -enum -offset indent.ItFor.Fa sizesmaller than.Dv SMALL_SIZE_LIMIT ,.Fn memstat.Em will show statistics for caller requests under.Fa size , but "percent used" information about such blocks will be reported under.Dv SMALL_SIZE_LIMIT Ns No -sizedblocks.  .ItAs a general case of point 1, internal statistics are reported on the theline corresponding to.Va new_size ,so that, for a given caller-supplied.Fa size ,the associated internal information will appear on that line or on the nextline which shows "percent used" information..El.Pp.Sy NOTE :If the caller returns blocks of a given.Fa sizeand requests others of .Fa size Ns No -s which map to the same internal.Va new_size ,it is possible for.Fn memstatsto report usage of greater than 100% for blocks of size.Va new_size .This should be viewed as A Good Thing..Sh RETURN VALUESThe function.Fn memgetreturns a .No non- Ns Dv NULLpointer to a block of memory of the requested.Fa size .It returns.Dv NULLif either the.Fa sizeis invalid (less than or equal to zero) or a .Xr malloc 3of a new block of memory fails.  In the former case, .Va errnois set to .Dv EINVAL ; in the latter, it is set to.Dv ENOMEM ..PpNeither.Fn memputnor.Fn memstatsreturn a value..\" This next request is for sections 1, 6, 7 & 8 only.\" .Sh ENVIRONMENT.\" .Sh FILES.\" .Sh EXAMPLES.\" This next request is for sections 1, 6, 7 & 8 only.\"     (command return values (to shell) and.\"    fprintf/stderr type diagnostics).\" .Sh DIAGNOSTICS.\" The next request is for sections 2 and 3 error.\" and signal handling only..Sh ERRORS.Va errnois set as follows:.Bl -tag -width "ENOMEM  " -offset indent.It Dv EINVALset by both.Fn memgetand.Fn memputif the .Fa sizeis zero or negative.It Dv ENOMEMset by .Fn memgetif a call to.Xr malloc 3fails.El.Sh SEE ALSO.Xr free 3 ,.Xr malloc 3 ..\" .Sh STANDARDS.\" .Sh HISTORY.Sh AUTHORSSteven J. Richardson and Paul Vixie, Vixie Enterprises..\" .Sh BUGS