Next: , Previous: Memory Object Creation, Up: External Memory Management


6.3 Memory Object Termination

— Function: kern_return_t memory_object_terminate (memory_object_t memory_object, memory_object_control_t memory_control, memory_object_name_t memory_object_name)
— Function: kern_return_t seqnos_memory_object_terminate (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, memory_object_name_t memory_object_name)

The function memory_object_terminate indicates that the kernel has completed its use of the given memory object. All rights to the memory object control and name ports are included, so that the memory manager can destroy them (using mach_port_deallocate) after doing appropriate bookkeeping. The kernel will terminate a memory object only after all address space mappings of that memory object have been deallocated, or upon explicit request by the memory manager.

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.) memory_object_name is a port used by the kernel to refer to the memory object data in response to vm_region calls.

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_destroy (memory_object_control_t memory_control, kern_return_t reason)

The function memory_object_destroy tells the kernel to shut down the memory object. As a result of this call the kernel will no longer support paging activity or any memory_object calls on this object, and all rights to the memory object port, the memory control port and the memory name port will be returned to the memory manager in a memory_object_terminate call. If the memory manager is concerned that any modified cached data be returned to it before the object is terminated, it should call memory_object_lock_request with should_flush set and a lock value of VM_PROT_WRITE before making this call.

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. reason is an error code indicating why the object must be destroyed.

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