RTCSETDEVICEMEMORYMONITORFUNCTION(3embree3)

💖 rtcSetDeviceMemoryMonitorFunction 💖

okay bestie, welcome to the rtcSetDev...orFunction(3) page from the Embree Ray Tracing Kernels 3 manual ✨ it's giving memory-watchdog energy and honestly? we're obsessed. this is the one where you get to spy on how much memory your Embree device is munching 👀🍓

---

✨ NAME ✨

rtcSetDeviceMemoryMonitorFunction — registers a callback function to track memory consumption 🧚💜

---

🌸 SYNOPSIS 🌸

#include <embree3/rtcore.h>

typedef bool (*RTCMemoryMonitorFunction)(
  void* userPtr,
  ssize_t bytes,
  bool post
);

void rtcSetDeviceMemoryMonitorFunction(
  RTCDevice device,
  RTCMemoryMonitorFunction memoryMonitor,
  void* userPtr
);

---

🦋 DESCRIPTION 🦋

so basically, with the rtcSetDeviceMemoryMonitorFunction call you can register a callback function (that's the memoryMonitor argument 💅) with a payload (the userPtr argument 🎀) for a device (yep, the device argument 👑). and that callback gets called whenever internal memory is allocated or deallocated by objects of that device. literally every time. no cap.

with this memory monitor callback mechanism, your application can track the memory consumption of an Embree device, and — if you're feeling dramatic — optionally terminate API calls that are consuming way too much memory 😭💀

lowkey important: only a single callback function can be registered per device. further invocations overwrite the previously set callback function. and passing NULL as the function pointer disables the registered callback function entirely. periodt.

once registered, the Embree device will invoke the memory monitor callback function before or after it allocates or frees important memory blocks. the callback function gets passed:

• the payload as specified at registration time — that's the userPtr argument 🫶
• the number of bytes allocated or deallocated — that's the bytes argument
• whether the callback is invoked after the allocation or deallocation took place — that's the post argument

and heads up bestie: the callback function might get called from multiple threads concurrently. so like, be normal about it and be thread-safe. 🙈

---

🌈 tracking your memory usage

your application can track the current memory usage of the Embree device by atomically accumulating the bytes input parameter provided to the callback function. that parameter will be >0 for allocations and <0 for deallocations. it's giving accounting but make it ✨thread-safe✨.

---

⭐ to cancel or not to cancel

Embree will continue its operation normally when you return true from the callback function. easy. chill. slay. 💅

but if false is returned, Embree will cancel the current operation with the RTC_ERROR_OUT_OF_MEMORY error code. and yes — issuing multiple cancel requests from different threads is allowed 👯

⚠️ cancelling will only happen when the callback was called for allocations (bytes > 0). otherwise the cancel request will just be ignored. sorry babe, that's the rule.

---

🎀 the post-argument lore (iykyk)

this part matters, don't skip it:

• if a callback to cancel was invoked before the allocation happens (post == false), then the bytes parameter should not be accumulated — because the allocation will never happen 🚫
• if the callback to cancel was invoked after the allocation happened (post == true), then the bytes parameter should be accumulated — because the allocation properly happened, and a deallocation will later free that data block ✅

like, the math has to math. fr fr.

---

💀 EXIT STATUS 💀

on failure an error code is set that can be queried using rtcGetDeviceError 🫠

---

👑 SEE ALSO 👑

• [rtcNewDevice]

---

and that's the whole page, bestie!! this was rtcSetDev...orFunction(3) from the Embree Ray Tracing Kernels 3 manual, brought to you with so much love and exactly zero skipped details 🫶✨ now go monitor that memory. main character energy only. bye!! 💖🌸🦋