Retrieve a handle to a system event.
#include <zircon/syscalls.h> zx_status_t zx_system_get_event(zx_handle_t root_job, uint32_t kind, zx_handle_t* event);
root_job must be a handle to the root job of the system.
kind must be one of the following:
ZX_SYSTEM_EVENT_OUT_OF_MEMORY - An event will be returned that will assert ZX_EVENT_SIGNALED when the system is nearing an out-of-memory situation. A process that is waiting on this event must quickly perform any important shutdown work. It is unspecified how much memory is available at the time this event is signaled, and unspecified how long the waiting process has to act before the kernel starts terminating processes or starting a full system reboot.
ZX_SYSTEM_EVENT_MEMORY_PRESSURE_CRITICAL - An event will be returned that will assert ZX_EVENT_SIGNALED when available memory on the system is critically low. The memory pressure level in this case is less severe than in the case of ZX_SYSTEM_EVENT_OUT_OF_MEMORY. The exact amount of memory available at the time the event is signaled is unspecified.
ZX_SYSTEM_EVENT_MEMORY_PRESSURE_WARNING - An event will be returned that will assert ZX_EVENT_SIGNALED when available memory on the system is approaching the critically low range. The memory pressure level in this case is less severe than in the case of ZX_SYSTEM_EVENT_MEMORY_PRESSURE_CRITICAL. The exact amount of memory available at the time the event is signaled is unspecified.
ZX_SYSTEM_EVENT_MEMORY_PRESSURE_NORMAL - An event will be returned that will assert ZX_EVENT_SIGNALED when available memory on the system is healthy. The exact amount of memory available at the time the event is signaled is unspecified.
The kernel will assert ZX_EVENT_SIGNALED on these four events in the following order of increasing severity: ZX_SYSTEM_EVENT_MEMORY_PRESSURE_NORMAL, ZX_SYSTEM_EVENT_MEMORY_PRESSURE_WARNING, ZX_SYSTEM_EVENT_MEMORY_PRESSURE_CRITICAL, ZX_SYSTEM_EVENT_OUT_OF_MEMORY. Exactly one of these events will assert ZX_EVENT_SIGNALED at a given time.
Both ZX_SYSTEM_EVENT_OUT_OF_MEMORY and ZX_SYSTEM_EVENT_MEMORY_PRESSURE_* retrieve events corresponding to system memory pressure levels, but there is a key difference in the way these events are intended to be used. A process waiting on the any of the ZX_SYSTEM_EVENT_MEMORY_PRESSURE_* events must undertake actions that free up memory and attempt to relieve the memory pressure on the system. On the other hand, a process waiting on the ZX_SYSTEM_EVENT_OUT_OF_MEMORY event must perform necessary actions in preparation for a clean shutdown - at this point it is too late to attempt recovery to a healthy memory pressure level.
None.
zx_system_get_event() returns ZX_OK on success, and event will be a valid handle, or an error code from below on failure.
ZX_ERR_ACCESS_DENIED The calling process' policy was invalid, the handle root_job did not have ZX_RIGHT_MANAGE_PROCESS rights for kind ZX_SYSTEM_EVENT_OUT_OF_MEMORY, root_job was not the root job of the system.
ZX_ERR_INVALID_ARGS kind was not one of the supported values specified above.
