setPurgeable

Control the purgeable status of a memory descriptors memory.

Declaration

virtual IOReturn setPurgeable(
 IOOptionBitsnewState, 
 IOOptionBits *oldState ); 

Parameters

newState

- the desired new purgeable state of the memory:

kIOMemoryPurgeableKeepCurrent - make no changes to the memory's purgeable state.

kIOMemoryPurgeableVolatile - make the memory volatile - the memory may be reclaimed by the VM system without saving its contents to backing store.

kIOMemoryPurgeableNonVolatile - make the memory nonvolatile - the memory is treated as with usual allocations and must be saved to backing store if paged.

kIOMemoryPurgeableEmpty - make the memory volatile, and discard any pages allocated to it.

oldState

- if non-NULL, the previous purgeable state of the memory is returned here:

kIOMemoryPurgeableNonVolatile - the memory was nonvolatile.

kIOMemoryPurgeableVolatile - the memory was volatile but its content has not been discarded by the VM system.

kIOMemoryPurgeableEmpty - the memory was volatile and has been discarded by the VM system.

Return Value

An IOReturn code.

Overview

Buffers may be allocated with the ability to have their purgeable status changed - IOBufferMemoryDescriptor with the kIOMemoryPurgeable option, VM_FLAGS_PURGEABLE may be passed to vm_allocate() in user space to allocate such buffers. The purgeable status of such a buffer may be controlled with setPurgeable(). The process of making a purgeable memory descriptor non-volatile and determining its previous state is atomic - if a purgeable memory descriptor is made nonvolatile and the old state is returned as kIOMemoryPurgeableVolatile, then the memory's previous contents are completely intact and will remain so until the memory is made volatile again. If the old state is returned as kIOMemoryPurgeableEmpty then the memory was reclaimed while it was in a volatile state and its previous contents have been lost.

See Also

Miscellaneous

- complete

Complete processing of the memory after an I/O transfer finishes.

- createMappingInTask

Maps a IOMemoryDescriptor into a task.

- getDirection

Accessor to get the direction the memory descriptor was created with.

- getLength

Accessor to get the length of the memory descriptor (over all its ranges).

- getPageCounts

Retrieve the number of resident and/or dirty pages encompassed by an IOMemoryDescriptor.

- getPhysicalAddress

Return the physical address of the first byte in the memory.

- getPhysicalSegment

Break a memory descriptor into its physically contiguous segments.

- getTag

Accessor to the retrieve the tag for the memory descriptor.

- initWithOptions

Master initialiser for all variants of memory descriptors. For a more complete description see IOMemoryDescriptor::withOptions.

- map

Maps a IOMemoryDescriptor into the kernel map.

- performOperation

Perform an operation on the memory descriptor's memory.

- prepare

Prepare the memory for an I/O transfer.

- readBytes

Copy data from the memory descriptor's buffer to the specified buffer.

- setMapping

Establishes an already existing mapping.

- setTag

Set the tag for the memory descriptor.

- withAddress

Create an IOMemoryDescriptor to describe one virtual range of the kernel task.

- withAddressRange

Create an IOMemoryDescriptor to describe one virtual range of the specified map.

- withAddressRanges

Create an IOMemoryDescriptor to describe one or more virtual ranges.

- withOptions

Master initialiser for all variants of memory descriptors.

- withPersistentMemoryDescriptor

Copy constructor that generates a new memory descriptor if the backing memory for the same task's virtual address and length has changed.

- withPhysicalAddress

Create an IOMemoryDescriptor to describe one physical range.

- writeBytes

Copy data to the memory descriptor's buffer from the specified buffer.