RTCSETDEVICEMEMORYMONITORFUNCTION(3embree4)

💖 rtcSetDeviceMemoryMonitorFunction — the memory-watching bestie of the Embree Ray Tracing Kernels 4 💖

okay so bestie, pull up a chair 🫶 we're talking about rtcSetDeviceMemoryMonitorFunction, and it lives in the Embree Ray Tracing Kernels 4 manual. It's literally the vibe check for your device's memory. Let's go ✨

---

🌸 NAME 🌸

rtcSetDeviceMemoryMonitorFunction — registers a callback function to track memory consumption 👀💾

---

✨ SYNOPSIS ✨

#include <embree4/rtcore.h>

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

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

---

🎀 DESCRIPTION 🎀

So the tea is: with the rtcSetDeviceMemoryMonitorFunction call, you can register a callback function (that's the memoryMonitor argument) with a payload (that's the userPtr argument) for a device (yep, the device argument). That callback gets called whenever internal memory is allocated or deallocated by objects belonging to that device. It's giving surveillance but make it legal 💅

With this memory monitor callback mechanism, your application can track the memory consumption of an Embree device, and — if you're feeling spicy — optionally terminate API calls that are eating too much memory. Iconic.

Only a single callback function can be registered per device, no cap. Any further invocations overwrite the previously set callback function. And if you pass NULL as the function pointer? That disables the registered callback function. Bye bestie 👋

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 (the userPtr argument) 🎁
• the number of bytes allocated or deallocated (the bytes argument) 📏
• whether the callback is invoked after the allocation or deallocation took place (the post argument) ⏱️

heads up bestie: the callback function might get called from multiple threads concurrently. so keep it thread-safe, fr fr 😭

Your application can track the current memory usage of the Embree device by atomically accumulating the bytes input parameter handed to the callback function. That parameter will be >0 for allocations and <0 for deallocations. Math but make it cute ✨

Embree will continue its operation normally when you return true from the callback function. But if you return false, Embree will cancel the current operation with the RTC_ERROR_OUT_OF_MEMORY error code. dramatic but deserved 💀

Issuing multiple cancel requests from different threads is allowed. Canceling will only happen when the callback was called for allocations (bytes > 0), otherwise the cancel request will be ignored. So yeah, no cancelling on deallocations, that's just not a thing 🚫

Now here's the important bit, 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, as 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, as the allocation properly happened and a deallocation will later free that data block. ✅

---

🔥 EXIT STATUS 🔥

On failure an error code is set that can be queried using rtcGetDeviceError. So like, always check, bestie 👑

---

👀 SEE ALSO 👀

• [rtcNewDevice]

---

and that's the whole page, you ate that 💅💖 stay slay, stay memory-aware. this lil lecture came to you straight from the Embree Ray Tracing Kernels 4 manual, page rtcSetDev...orFunction(3), no date on the footer so we're keeping it timeless, periodt 🎀✨🦋