SetOOMEvent (Windows Embedded CE 6.0)

  • Article

1/5/2010

This function enables enhanced memory management features of Windows Embedded CE. This function is callable from kernel mode only.

Syntax

void SetOOMEvent(
  HANDLE hEvent,
  DWORD cpLow,
  DWORD cpCritical,
  DWORD cpLowBlockSize,
  DWORD cpCriticalBlockSize 
);

Parameters

  • hEvent
    [in] Handle to the event that the kernel sets when memory becomes low or critically low.
  • cpLow
    [in] Number of free memory pages that triggers a low memory condition. When memory goes below this level, hEvent is set.
  • cpCritical
    [in] Number of free memory pages that triggers a critically low memory condition. When memory goes below this level, hEvent is set.
  • cpLowBlockSize
    [in] Size of the largest block that the kernel allocates with the VirtualAlloc function, when the allocation would leave the system with fewer than cpLow pages.
  • cpCriticalBlockSize
    [in] Size of the largest block that the kernel allocates with VirtualAlloc, when the allocation would leave the system with fewer than cpCritical pages.

Return Value

None.

Remarks

This function replaces SetGwesOOMEvent, which is now obsolete.

There is no need to call this function in an OS configuration that includes the OOM component. The OOM component calls this function and relies on registry settings to define the OEM's preferred memory settings.

If there are no registry settings, the OOM component uses the following parameter defaults:

  • cpLow = 32
  • cpCritical = 20
  • cpLowBlockSize = 4
  • cpCriticalBlockSize = 2

If an OEM does not include the OOM component, the OEM must call this function to enable control of the following resources:

  • Page-out code. When memory is low, the kernel pages out or discards code that is marked discardable. This enables memory to be freed for use by other processes.
  • Reclaim unused stack space. When memory is low, the kernel attempts to reclaim memory used by a thread's stack that is no longer needed by the thread.

If this function is not called, the following defaults for the system are used:

  • cpLow = 0
  • cpCritical = 0
  • cpLowBlockSize = 0
  • cpCriticalBlockSize = 0

The kernel does not attempt to page out code until memory reaches zero, and it does not reclaim unused stack memory. However, memory is reclaimed when threads, processes, memory, and kernel objects are deleted.

In some circumstances, a system that does not discard memory or reclaim stack memory is usable by OEMs. An OEM must completely investigate the issues before deciding not to call this function.

An application that needs to monitor a memory state would pass in the parameters and then wait for the event to be triggered by the kernel by calling the function WaitForSingleObject.

When the kernel sets the event, the monitoring application would query the memory state to determine if memory is low or critical, and then take appropriate action. To query the current memory state, use the GlobalMemoryStatus function.

Requirements

Header pkfuncs.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later

See Also

Reference

Other OAL Functions
dwNKMaxPrioNoScav

Other Resources

Kernel Mode APIs
GlobalMemoryStatus
VirtualAlloc
WaitForSingleObject
Out-of-Memory Registry Settings