Tcl_Alloc(3tcl)

✨ Tcl_Alloc — the 3tcl manual page, bestie edition 💖

okay so. you know how C's malloc() and free() are just... out there, doing whatever, platform by platform, compiler by compiler? yeah. not here. this page is the whole friend group: Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc. they're all about one thing: allocate or free heap memory. let's get into it 🫶

🌸 NAME 🌸

Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc — allocate or free heap memory. that's the whole assignment. 🎀

✨ SYNOPSIS ✨

#include <tcl.h>

char *
Tcl_Alloc(size)

void
Tcl_Free(ptr)

char *
Tcl_Realloc(ptr, size)

char *
Tcl_AttemptAlloc(size)

char *
Tcl_AttemptRealloc(ptr, size)

void
Tcl_GetMemoryInfo(dsPtr)

char *
ckalloc(size)

void
ckfree(ptr)

char *
ckrealloc(ptr, size)

char *
attemptckalloc(size)

char *
attemptckrealloc(ptr, size)

like. look at that lineup. eleven whole functions and every single one of them is here to do one (1) thing and do it well. 💅

🌈 ARGUMENTS 🌈

• unsigned int size (in) — size in bytes of the memory block to allocate. yes bestie, bytes, not vibes. ✨
• char *ptr (in) — pointer to the memory block you wanna free or realloc. the block in question. the one. 🔥
• Tcl_DString *dsPtr (in) — an initialized DString pointer. key word: initialized. don't come in here with an uninitialized one, it's giving chaos. 😭

💖 DESCRIPTION 💖

okay so these procedures are giving us a platform and compiler independent interface for memory allocation. that's the whole point. if your program needs to hand off ownership of memory blocks between Tcl and other modules, you use these routines — not the native malloc() and free() from the C run-time library. no cap. 🙅♀️

Tcl_Alloc returns a pointer to a block of at least size bytes, and it's suitably aligned for any use. she's versatile, she's aligned, she's iconic. 👑

Tcl_Free makes the space referred to by ptr available for further allocation. releasing it back into the wild. 🦋

Tcl_Realloc changes the size of the block pointed to by ptr to size bytes, and returns a pointer to the new block. the contents stay unchanged up to the lesser of the new and old sizes — so no surprise content loss, we love that for us. 🥰 important: the returned location may be different from ptr. do not assume it's the same spot. and if ptr is NULL, this is equivalent to calling Tcl_Alloc with just the size argument. cute shortcut, honestly.

Tcl_AttemptAlloc and Tcl_AttemptRealloc are identical in function to Tcl_Alloc and Tcl_Realloc, except — and this is the part that matters — they will not cause the Tcl interpreter to panic if the memory allocation fails. if the allocation fails, these functions return NULL. graceful decline instead of full-on meltdown. 💀

⚠️ heads up bestie: on some platforms, but not all, attempting to allocate a zero-sized block of memory will also cause these functions to return NULL. so don't be out here assuming zero-size = free success. platforms are messy. 🙈

the procedures ckalloc, ckfree, ckrealloc, attemptckalloc, and attemptckrealloc are implemented as macros. normally, they are synonyms for the corresponding procedures documented on this page. however — when Tcl and all modules calling Tcl are compiled with TCL_MEM_DEBUG defined, these macros get redefined to be special debugging versions of these procedures. so if you want Tcl's memory debugging to work inside a module, use the macros rather than direct calls to Tcl_Alloc, etc. that's the move. periodt. 💅

Tcl_GetMemoryInfo appends a list-of-lists of memory stats to the provided DString. two things you need to know though:

1. this function cannot be used in stub-enabled extensions. 🚫
2. it is only available if Tcl is compiled with the threaded memory allocator. so check before you reach for it. 🌸

⭐ KEYWORDS ⭐

alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG

and that's the whole page, bestie!! 🎀 this one's from the Tcl 7.5 era and it's filed under Tcl_Alloc(3tcl) in the manual pages — old-school but still out here keeping your heap safe and sound. go allocate responsibly. i'm obsessed with you. 🫶💖✨