ici::doc::pod3::memmgr(3)

💖 ici::doc::pod3::memmgr(3) — the memory manager page, bestie edition 💖

okay so this is memmgr(3) from the ICI library functions and honestly? she's iconic. she's the girl who keeps all the other memory managers from fighting at the party. let's get into it 🫶

---

✨ NAME ✨

memmgr — memory manager abstraction functions. literally the vibe coordinator for all your memory management. 💅

---

🌸 SYNOPSIS 🌸

#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);

(no we are not fixing that missing ) in the last line of the prototypes, it's part of the lore, it's in the original, periodt 💀)

---

👑 DESCRIPTION 👑

memmgr is an abstraction layer for administration of memory management. it's giving ✨middle management but make it useful✨. it enables multiple memory managers to coexist in a single application, which is honestly so brave of it.

every memory manager specification is required to include:

• pointers to a memory allocation function
• a memory deallocation function
• functions for translating between local memory pointers and "addresses", which are abstract memory locations that have private meaning to the manager (iykyk)

the allocation function is expected to return a block of memory of size size (in bytes), initialized to all binary zeroes. so it comes pre-cleaned, we love a tidy queen 🌸

the fileName and lineNbr 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 sptrace(3) that may be implemented by the underlying memory management system. tracking, but make it helpful 💅

---

🎀 managers have names AND numbers, she contains multitudes 🎀

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. no cap. (well, actually cap: 7.)

however — and this is the messy part — 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. shared name = shared understanding = friendship 🫶

the memory manager with manager number 0 is always available. her name is "std". her memory allocation function is calloc(), her deallocation function is free(), and her pointer/address translation functions are merely casts. she's lowkey the blueprint.

---

🌈 the functions, one by one 🌈

• 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 (she's chill like that). name is the name of the memory manager. take is a pointer to the manager's memory allocation function; release is a pointer to the manager's memory deallocation function. AtoP is a pointer to the manager's function for converting an address to a local memory pointer; PtoA is a pointer to the manager's pointer-to-address converter function. returns the memory manager ID number assigned to the named manager, or -1 on any error.

⚠️ NOTE: memmgr_add() is NOT thread-safe. in a multithreaded execution image (e.g., VxWorks), all memory managers should be loaded before any subordinate threads or tasks are spawned. do not test her. she will not pass. 💀

• int memmgr_find(char *name) — return the memmgr ID of the named manager, or -1 if not found. a simple "do you know her?" 🔍
• char *memmgr_name(int mgrId) — return the name of the manager given by mgrId. name reveal ✨
• MemAllocator memmgr_take(int mgrId) — return the allocator function pointer for the manager given by mgrId. the one who takes 🫴
• memDeallocator memmgr_release(int mgrId) — return the deallocator function pointer for the manager given by mgrId. the one who releases 🫳
• MemAtoPConverter memmgr_AtoP(int mgrId) — return the address-to-pointer converter function pointer for the manager given by mgrId.
• MemPtoAConverter memmgr_PtoA(int mgrId) — return the pointer-to-address converter function pointer for the manager given by 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); — memmgr_open() opens one avenue of access to a PSM managed region of shared memory, initializing as necessary.

in order for multiple tasks to share access to this memory region, all must cite the same memkey and partitionName when they call memmgr_open(). if shared access is not necessary, then memKey can be SM_NO_KEY and partitionName can be any valid partition name. (solo mission, valid.)

if it is known that a prior invocation of memmgr_open() has already initialized the region, then memSize can be zero and memPtr must be NULL. otherwise memSize is required, and the required value of memPtr 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 memPtr points to must contain the address of that memory region. otherwise, *memPtr must contain NULL.

memmgr_open() will allocate system memory as necessary and will in any case return the address of the shared memory region in *memPtr.

if the shared memory is newly allocated or otherwise not yet under PSM management, then memmgr_open() will invoke psm_manage() to manage the shared memory region. it will also add a catalogue for the managed shared memory region as necessary.

if memMgr is non-NULL, then memmgr_open() will additionally call memmgr_add() 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 memMgr. if that memory manager is newly created, then the supplied afn, ffn, apfn, and pafn functions (which can be written with reference to the memory manager index value returned in memMgr) have been established as the memory management functions for local private access to this managed shared memory region.

returns 0 on success, -1 on any error.

• void memmgr_destroy(int smId, PsmPartition *partition); — memmgr_destroy() terminates all access to a PSM managed region of shared memory, invoking psm_erase() to destroy the partition and sm_ShmDestroy() to destroy the shared memory object. it's the goodbye girl, and she does not do half-measures 😭

---

🦋 EXAMPLE 🦋

/* 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);
 }

look at her go. find, take, release, allocate, free. the whole character arc in like ten lines. ate and left no crumbs 👑

---

🔥 SEE ALSO 🔥

• psm(3)

---

and that's the whole page bestie!! this one's from perl v5.24.1, dated 2016-07-07, and it lives under ici::doc::pod3::memmgr(3) — she's been serving since 2016 and she has NOT slowed down 💜 mwah, go forth and manage your memory responsibly 🎀✨