1rtcSetDeviceMemoryMonitorFEumnbcrteieonR(a3y)TracingrtKceSrenteDlesvi3ceMemoryMonitorFunction(3)
2
3
4
5   NAME
6              rtcSetDeviceMemoryMonitorFunction - registers a callback function
7                to track memory consumption
8
9   SYNOPSIS
10              #include <embree3/rtcore.h>
11
12              typedef bool (*RTCMemoryMonitorFunction)(
13                void* userPtr,
14                ssize_t bytes,
15                bool post
16              );
17
18              void rtcSetDeviceMemoryMonitorFunction(
19                RTCDevice device,
20                RTCMemoryMonitorFunction memoryMonitor,
21                void* userPtr
22              );
23
24   DESCRIPTION
25       Using  the  rtcSetDeviceMemoryMonitorFunction  call,  it is possible to
26       register a callback  function  (memoryMonitor  argument)  with  payload
27       (userPtr  argument)  for  a  device  (device argument), which is called
28       whenever internal memory is allocated or deallocated by objects of that
29       device.   Using this memory monitor callback mechanism, the application
30       can track the memory consumption of an Embree  device,  and  optionally
31       terminate API calls that consume too much memory.
32
33       Only  a single callback function can be registered per device, and fur‐
34       ther invocations overwrite the previously set callback function.  Pass‐
35       ing NULL as function pointer disables the registered callback function.
36
37       Once registered, the Embree device will invoke the memory monitor call‐
38       back function before or after it allocates or  frees  important  memory
39       blocks.   The callback function gets passed the payload as specified at
40       registration time (userPtr argument), the number of bytes allocated  or
41       deallocated (bytes argument), and whether the callback is invoked after
42       the allocation or deallocation took place (post argument).   The  call‐
43       back function might get called from multiple threads concurrently.
44
45       The application can track the current memory usage of the Embree device
46       by atomically accumulating the bytes input parameter  provided  to  the
47       callback  function.   This  parameter will be >0 for allocations and <0
48       for deallocations.
49
50       Embree will continue its operation normally when  returning  true  from
51       the  callback  function.   If false is returned, Embree will cancel the
52       current operation with the RTC_ERROR_OUT_OF_MEMORY error code.  Issuing
53       multiple  cancel requests from different threads is allowed.  Canceling
54       will only happen when the callback was called for allocations (bytes  >
55       0), otherwise the cancel request will be ignored.
56
57       If  a  callback  to  cancel  was  invoked before the allocation happens
58       (post == false), then the bytes parameter should not be accumulated, as
59       the  allocation  will  never  happen.   If  the  callback to cancel was
60       invoked after the allocation happened (post == true),  then  the  bytes
61       parameter  should  be  accumulated, as the allocation properly happened
62       and a deallocation will later free that data block.
63
64   EXIT STATUS
65       On failure an error code is  set  that  can  be  queried  using  rtcDe‐
66       viceGetError.
67
68   SEE ALSO
69       [rtcNewDevice]
70
71
72
73                                          rtcSetDeviceMemoryMonitorFunction(3)