— Function: kern_return_t memory_object_lock_request (memory_object_control_t memory_control, vm_offset_t offset, vm_size_t size, memory_object_return_t should_clean, boolean_t should_flush, vm_prot_t lock_value, mach_port_t reply_to)

The function memory_object_lock_request allows a memory manager to make cache management requests. As specified in arguments to the call, the kernel will:

• clean (i.e., write back using memory_object_data_supply or memory_object_data_write) any cached data which has been modified since the last time it was written
• flush (i.e., remove any uses of) that data from memory
• lock (i.e., prohibit the specified uses of) the cached data

Locks applied to cached data are not cumulative; new lock values override previous ones. Thus, data may also be unlocked using this primitive. The lock values must be one or more of the following values: VM_PROT_NONE, VM_PROT_READ, VM_PROT_WRITE, VM_PROT_EXECUTE and VM_PROT_ALL as defined in mach/vm_prot.h.

Only data which is cached at the time of this call is affected. When a running thread requires a prohibited access to cached data, the kernel will issue a memory_object_data_unlock call specifying the forms of access required.

Once all of the actions requested by this call have been completed, the kernel issues a memory_object_lock_completed call on the specified reply port.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. offset is an offset within a memory object, in bytes. This must be page aligned. size is the amount of cached data (starting at offset) to be handled. This must be an integral number of the memory object page size. If should_clean is set, modified data should be written back to the memory manager. If should_flush is set, the specified cached data should be invalidated, and all uses of that data should be revoked. lock_value is a protection value indicating those forms of access that should not be permitted to the specified cached data. reply_to is a port on which a memory_object_lock_completed call should be issued, or MACH_PORT_NULL if no acknowledgement is desired.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

— Function: kern_return_t memory_object_lock_completed (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length)
— Function: kern_return_t seqnos_memory_object_lock_completed (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length)

The function memory_object_lock_completed indicates that a previous memory_object_lock_request has been completed. Note that this call is made on whatever port was specified in the memory_object_lock_request call; that port need not be the memory object port itself. No reply is expected after this call.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. length is the length of the data covered by the lock request.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

— Function: kern_return_t memory_object_data_unlock (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length, vm_prot_t desired_access)
— Function: kern_return_t seqnos_memory_object_data_unlock (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length, vm_prot_t desired_access)

The function memory_object_data_unlock is a request that the memory manager permit at least the desired access to the specified data cached by the kernel. A call to memory_object_lock_request is expected in response.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. This will be page aligned. length is the number of bytes of data, starting at offset, to which this call refers. This will be an integral number of memory object pages. desired_access a protection value describing the memory access modes which must be permitted on the specified cached data. One or more of: VM_PROT_READ, VM_PROT_WRITE or VM_PROT_EXECUTE.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.