IMcResourceManagerReserveMemory Method

Parameters

Type

Type: MediaCy.IQL.EnginemcMemoryType

PcntOrMBytes

Type: SystemDouble
On entry, this should be set to the number of MBytes or percentage of usable-physical requested to reserve. On exit, the value is set to the number of MBytes or percentage that could be reserved (that is, it will be unchanged for successful reservations). If this value is zero or less on entry, then on exit it is set to the currently available amount of reservable memory of the given type; in this case the returned handle value is zero since no reservation is made. The mcmtMBytesFlag bit of the type determines if the value is treated as MBytes or as a percentage, as discussed in Remarks.

Description

Type: SystemString

Flags

Type: MediaCy.IQL.EnginemcReserveMemoryFlags

Return Value

Type: IntPtr
For a successful reservation, a handle to the reserved block, which will be used to release or refresh the reservation. Nothing is returned if the requested reservation cannot be made or if PcntOrMBytes is zero on entry.

This function does not actually allocate memory; see the Windows Virtual Memory functions (VirtualAlloc�) for the various allocation options available. In general large memory allocations are done using VirtualAlloc which provides the best control of the allocation timing, but if the memory has to be locked immediately malloc is equivalent. There are three categories of reservations: virtual memory (types mcmtVirtualMemory and mcmtVirtualMemoryMBytes), managed image memory (types mcmtImageMemory and mcmtImageMemoryMBytes) and physical memory (types mcmtPhysicalMemory and mcmtPhysicalMemoryMBytes). Each of these pairs of types differs by the presence or absence of the mcmtMBytesFlag, which controls whether the PcntOrMBytes argument is interpreted as a percentage (of what is explained later) or as MBytes. The total amount of reservable virtual memory, MemoryMax(mcmtVirtualMemory or mcmtVirtualMemoryMBytes), is that set by a call to SetMemoryLimit(mcmtVirtualMemory or mcmtVirtualMemoryMBytes). Virtual memory is almost never a problem in the x64 versions of IQL. However, even in 32-bit applications running under a 32-bit OS (where the total amount of virtual memory may be as little as 2GB), the total quantity of virtual memory is usually not the limiting factor for successful allocations. Rather the limit is usually the largest contiguous block of free virtual memory; this is the value that the MemoryFree(mcmtVirtualMemory or mcmtVirtualMemoryMBytes) property exposes and allows you to attempt to free up by assignment. Thus, a McResourceManager aware task should both reserve a block of virtual memory by calling ReserveMemory with type mcmtVirtualMemory or mcmtVirtualMemoryMBytes and then assign the size of the needed block to MemoryFree(mcmtVirtualMemory or mcmtVirtualMemoryMBytes) before attempting the actual VirtualAlloc call to do the allocation. For virtual memory related requests a percentage value denoted by absence of the mcmtMBytesFlag bit on the type (that is, mcmtVirtualMemory as opposed to mcmtVirtualMemoryMBytes) refers to the percentage of total virtual memory the operating system makes available to the process. This total will be either 2, 3, 4 or 8192 GB, depending on the operating system setup and version of the application. For managed image memory (types mcmtImageMemory and mcmtImageMemoryMBytes) and physical memory (types mcmtPhysicalMemory and mcmtPhysicalMemoryMBytes) the reservable pool is shared, with image memory occupying a portion of this pool. The total reservable memory in this pool, MemoryMax(mcmtImageMemory or mcmtImageMemoryMBytes) and/or MemoryMax(mcmtPhysicalMemory or mcmtPhysicalMemoryMBytes), is set by calling SetMemoryLimit(mcmtImageMemory or mcmtImageMemoryMBytes) and/or SetMemoryLimit(mcmtPhysicalMemory or mcmtPhysicalMemoryMBytes). Reserved physical memory is never allowed to be smaller than reserved image memory; initially they are equal (that is, there is no excess reserved physical memory beyond that shared with image storage). For physical or image memory related requests, a percentage value denoted by absence of the mcmtMBytesFlag bit on the type (that is, mcmtImageMemory or mcmtPhysicalMemory as opposed to mcmtImageMemoryMBytes or mcmtPhysicalMemoryMBytes) refers to the percentage of "usable physical memory". "Usable physical memory" is total physical memory minus an amount reserved for use by external applications. It is the maximum amount of physical memory that is allowed for algorithm use; trying to use 100% of it is likely to result is decreased performance due to memory page-file swapping. A PropertyChanged( ID_IMcResourceManager_ReserveMemory, memoryHandle) event is fired after a successful registration. When flags is set to mcrmNone and the reserve request cannot be satisfied, the function will fail with an mceNO_MEMORY error. Before the failing exit, PcntOrMBytes will be set to the amount of memory available for reservation, and the property MemoryMissing is set to the difference between PcntOrMBytes and what is allowed. However, no PropertyChanged event is fired. Nothing is returned as the reserved block handle. By contrast, when flags is set to mcrmNoFailure and the reserve request cannot be satisfied, the property MemoryMissing is set to the difference between PcntOrMBytes and what is allowed and a PropertyChanged(ID_IMcResourceManager_MemoryMissing, MBytesNeeded) event is fired potentially allowing other owners of McResourceManager reserved memory to release it. After the PropertyChanged event handlers have all been called, then the a second check is made to see if the event handlers freed enough reserves to allow the request to succeed. If so, MemoryMissing is set to zero and the function succeeds by returning a non-zero handle to the reserved block. If there is still not enough reserves, PcntOrMBytes is set to the maximum available reservation and MemoryMissing is set to the difference between PcntOrMBytes and what is allowed, but no second PropertyChanged event is fired. During the PropertyChanged event, event handlers are allowed to release reserved memory or to refresh a block of reserved memory by asking for a smaller block, but recursive reservation failures are not allowed.