.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "ici::doc::pod3::memmgr 3" .TH ici::doc::pod3::memmgr 3 "2016-07-07" "perl v5.24.1" "ICI library functions" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" memmgr \- memory manager abstraction functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include "memmgr.h" \& \& typedef void *(* MemAllocator) \& (char *fileName, int lineNbr, size_t size); \& typedef void (* MemDeallocator) \& (char *fileName, int lineNbr, void * blk); \& typedef void *(* MemAtoPConverter) (unsigned int address); \& typedef unsigned int (* MemPtoAConverter) (void * pointer); \& \& unsigned int memmgr_add (char *name, \& MemAllocator take, \& MemDeallocator release, \& MemAtoPConverter AtoP, \& MemPtoAConverter PtoA); \& int memmgr_find (char *name); \& char *memmgr_name (int mgrId); \& MemAllocator memmgr_take (int mgrId); \& MemDeallocator memmgr_release (int mgrId); \& MemAtoPConverter memmgr_AtoP (int mgrId); \& MemPtoAConverter memmgr_PtoA (int mgrId; \& \& int memmgr_open (int memKey, \& unsigned long memSize, \& char **memPtr, \& int *smId, \& char *partitionName, \& PsmPartition *partition, \& int *memMgr, \& MemAllocator afn, \& MemDeallocator ffn, \& MemAtoPConverter apfn, \& MemPtoAConverter pafn); \& void memmgr_destroy (int smId, \& PsmPartition *partition); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\*(L"memmgr\*(R" is an abstraction layer for administration of memory management. It enables multiple memory managers to coexist in a single application. Each memory manager specification is required to include pointers to a memory allocation function, a memory deallocation function, and functions for translating between local memory pointers and \*(L"addresses\*(R", which are abstract memory locations that have private meaning to the manager. The allocation function is expected to return a block of memory of size \*(L"size\*(R" (in bytes), initialized to all binary zeroes. The \fIfileName\fR and \fIlineNbr\fR arguments to the allocation and deallocation functions are expected to be the values of _\|_FILE_\|_ and _\|_LINE_\|_ at the point at which the functions are called; this supports any memory usage tracing via \fIsptrace\fR\|(3) that may be implemented by the underlying memory management system. .PP Memory managers are identified by number and by name. The identifying number for a memory manager is an index into a private, fixed-length array of up to 8 memory manager configuration structures; that is, memory manager number must be in the range 0\-7. However, memory manager numbers are assigned dynamically and not always predictably. To enable multiple applications to use the same memory manager for a given segment of shared memory, a memory manager may be located by a predefined name of up to 15 characters that is known to all the applications. .PP The memory manager with manager number 0 is always available; its name is \*(L"std\*(R". Its memory allocation function is \fIcalloc()\fR, its deallocation function is \fIfree()\fR, and its pointer/address translation functions are merely casts. .IP "unsigned int memmgr_add(char *name, MemAllocator take, MemDeallocator release, MemAtoPConverter AtoP, MemPtoAConverter PtoA)" 4 .IX Item "unsigned int memmgr_add(char *name, MemAllocator take, MemDeallocator release, MemAtoPConverter AtoP, MemPtoAConverter PtoA)" Add a memory manager to the memory manager array, if not already defined; attempting to add a previously added memory manager is not considered an error. \fIname\fR is the name of the memory manager. \&\fItake\fR is a pointer to the manager's memory allocation function; \fIrelease\fR is a pointer to the manager's memory deallocation function. \fIAtoP\fR is a pointer to the manager's function for converting an address to a local memory pointer; \fIPtoA\fR is a pointer to the manager's pointer-to-address converter function. Returns the memory manager \s-1ID\s0 number assigned to the named manager, or \-1 on any error. .Sp \&\fI\s-1NOTE\s0\fR: \fImemmgr_add()\fR is \s-1NOT\s0 thread-safe. In a multithreaded execution image (e.g., VxWorks), all memory managers should be loaded \fIbefore\fR any subordinate threads or tasks are spawned. .IP "int memmgr_find(char *name)" 4 .IX Item "int memmgr_find(char *name)" Return the memmgr \s-1ID\s0 of the named manager, or \-1 if not found. .IP "char *memmgr_name(int mgrId)" 4 .IX Item "char *memmgr_name(int mgrId)" Return the name of the manager given by \fImgrId\fR. .IP "MemAllocator memmgr_take(int mgrId)" 4 .IX Item "MemAllocator memmgr_take(int mgrId)" Return the allocator function pointer for the manager given by \fImgrId\fR. .IP "memDeallocator memmgr_release(int mgrId)" 4 .IX Item "memDeallocator memmgr_release(int mgrId)" Return the deallocator function pointer for the manager given by \fImgrId\fR. .IP "MemAtoPConverter memmgr_AtoP(int mgrId)" 4 .IX Item "MemAtoPConverter memmgr_AtoP(int mgrId)" Return the address-to-pointer converter function pointer for the manager given by \fImgrId\fR. .IP "MemPtoAConverter memmgr_PtoA(int mgrId)" 4 .IX Item "MemPtoAConverter memmgr_PtoA(int mgrId)" Return the pointer-to-address converter function pointer for the manager given by \fImgrId\fR. .IP "int memmgr_open(int memKey, unsigned long memSize, char **memPtr, int *smId, char *partitionName, PsmPartition *partition, int *memMgr, MemAllocator afn, MemDeallocator ffn, MemAtoPConverter apfn, MemPtoAConverter pafn);" 4 .IX Item "int memmgr_open(int memKey, unsigned long memSize, char **memPtr, int *smId, char *partitionName, PsmPartition *partition, int *memMgr, MemAllocator afn, MemDeallocator ffn, MemAtoPConverter apfn, MemPtoAConverter pafn);" \&\fImemmgr_open()\fR opens one avenue of access to a \s-1PSM\s0 managed region of shared memory, initializing as necessary. .Sp In order for multiple tasks to share access to this memory region, all must cite the same \fImemkey\fR and \fIpartitionName\fR when they call \fImemmgr_open()\fR. If shared access is not necessary, then \fImemKey\fR can be \s-1SM_NO_KEY\s0 and \&\fIpartitionName\fR can be any valid partition name. .Sp If it is known that a prior invocation of \fImemmgr_open()\fR has already initialized the region, then \fImemSize\fR can be zero and \fImemPtr\fR must be \s-1NULL. \s0 Otherwise \fImemSize\fR is required and the required value of \fImemPtr\fR depends on whether or not the memory that is to be shared and managed has already been allocated (e.g., it's a fixed region of bus memory). If so, then the memory pointer variable that \fImemPtr\fR points to must contain the address of that memory region. Otherwise, \fI*memPtr\fR must contain \s-1NULL.\s0 .Sp \&\fImemmgr_open()\fR will allocate system memory as necessary and will in any case return the address of the shared memory region in \fI*memPtr\fR. .Sp If the shared memory is newly allocated or otherwise not yet under \&\s-1PSM\s0 management, then \fImemmgr_open()\fR will invoke \fIpsm_manage()\fR to manage the shared memory region. It will also add a catalogue for the managed shared memory region as necessary. .Sp If \fImemMgr\fR is non-NULL, then \fImemmgr_open()\fR will additionally call \&\fImemmgr_add()\fR to establish a new memory manager for this managed shared memory region, as necessary. The index of the applicable memory manager will be returned in \fImemMgr\fR. If that memory manager is newly created, then the supplied \fIafn\fR, \fIffn\fR, \fIapfn\fR, and \fIpafn\fR functions (which can be written with reference to the memory manager index value returned in \fImemMgr\fR) have been established as the memory management functions for local private access to this managed shared memory region. .Sp Returns 0 on success, \-1 on any error. .IP "void memmgr_destroy(int smId, PsmPartition *partition);" 4 .IX Item "void memmgr_destroy(int smId, PsmPartition *partition);" \&\fImemmgr_destroy()\fR terminates all access to a \s-1PSM\s0 managed region of shared memory, invoking \fIpsm_erase()\fR to destroy the partition and \fIsm_ShmDestroy()\fR to destroy the shared memory object. .SH "EXAMPLE" .IX Header "EXAMPLE" .Vb 2 \& /* this example uses the calloc/free memory manager, which is \& * called "std", and is always defined in memmgr. */ \& \& #include "memmgr.h" \& \& main() \& { \& int mgrId; \& MemAllocator myalloc; \& MemDeallocator myfree; \& char *newBlock; \& \& mgrId = memmgr_find("std"); \& myalloc = memmgr_take(mgrId); \& myfree = memmgr_release(mgrId); \& ... \& \& newBlock = myalloc(5000); \& ... \& myfree(newBlock); \& } .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIpsm\fR\|(3)