.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "rtcSetDeviceMemoryMonitorFunction" "3" "" "" "Embree Ray Tracing Kernels 4"
.hy
.SS NAME
.IP
.nf
\f[C]
rtcSetDeviceMemoryMonitorFunction - registers a callback function
  to track memory consumption
\f[R]
.fi
.SS SYNOPSIS
.IP
.nf
\f[C]
#include <embree4/rtcore.h>

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

void rtcSetDeviceMemoryMonitorFunction(
  RTCDevice device,
  RTCMemoryMonitorFunction memoryMonitor,
  void* userPtr
);
\f[R]
.fi
.SS DESCRIPTION
.PP
Using the \f[C]rtcSetDeviceMemoryMonitorFunction\f[R] call, it is
possible to register a callback function (\f[C]memoryMonitor\f[R]
argument) with payload (\f[C]userPtr\f[R] argument) for a device
(\f[C]device\f[R] argument), which is called whenever internal memory is
allocated or deallocated by objects of that device.
Using this memory monitor callback mechanism, the application can track
the memory consumption of an Embree device, and optionally terminate API
calls that consume too much memory.
.PP
Only a single callback function can be registered per device, and
further invocations overwrite the previously set callback function.
Passing \f[C]NULL\f[R] as function pointer disables the registered
callback function.
.PP
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 (\f[C]userPtr\f[R] argument), the number of bytes
allocated or deallocated (\f[C]bytes\f[R] argument), and whether the
callback is invoked after the allocation or deallocation took place
(\f[C]post\f[R] argument).
The callback function might get called from multiple threads
concurrently.
.PP
The application can track the current memory usage of the Embree device
by atomically accumulating the \f[C]bytes\f[R] input parameter provided
to the callback function.
This parameter will be >0 for allocations and <0 for deallocations.
.PP
Embree will continue its operation normally when returning
\f[C]true\f[R] from the callback function.
If \f[C]false\f[R] is returned, Embree will cancel the current operation
with the \f[C]RTC_ERROR_OUT_OF_MEMORY\f[R] error code.
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.
.PP
If a callback to cancel was invoked before the allocation happens
(\f[C]post == false\f[R]), then the \f[C]bytes\f[R] parameter should not
be accumulated, as the allocation will never happen.
If the callback to cancel was invoked after the allocation happened
(\f[C]post == true\f[R]), then the \f[C]bytes\f[R] parameter should be
accumulated, as the allocation properly happened and a deallocation will
later free that data block.
.SS EXIT STATUS
.PP
On failure an error code is set that can be queried using
\f[C]rtcGetDeviceError\f[R].
.SS SEE ALSO
.PP
[rtcNewDevice]