mach/task.h

The task_create function creates a new task from parent_task and returns the name of the new task in child_task. The child task acquires shared or copied parts of the parent's address space (see vm_inherit). The child task initially contains no threads. The child task inherits the parent's security ID. The child task receives the following "special" ports, which are created or copied for it at task creation: [task-self send right] The port by which the kernel knows the new child task and allows it to be manipulated. The child task holds a send right for this port. The port name is also returned to the calling task. [bootstrap send right] The port to which the child task can send a message requesting return of any system service ports that it needs (for example, a port to the Network Name Server or the Environment Manager). The child task inherits a send right for this port from the parent task. The task can use task_set_special_port to change this port. [host-self send right] The port by which the child task requests information about its host. The child task inherits a send right for this port from the parent task. [ledger send rights] The ports naming the ledgers from which the task draws its resources. The child task also inherits the following ports: [sample send right] The port to which PC sampling messages are to be sent. [exception send rights] Ports to which exception messages are sent. [registered send rights] Ports to system services.

Notes. The ledgers functionality mentioned above is not currently implemented.

The task_terminate function kills task and all its threads, if any. The kernel frees all resources that are in use by the task. The kernel destroys any port for which the task holds the receive right.

The task_threads function returns a list of the threads within task. The calling task or thread also receives a send right to the kernel port for each listed thread.

The mach_ports_register function registers an array of well-known system ports for the specified task. The task holds only send rights for the registered ports. The valid well-known system ports are: The port for the Name Server The port for the Environment Manager The port for the Service server Each port must be placed in a specific slot in the array. The slot numbers are defined (in mach.h) by the global constants NAME_SERVER_SLOT, ENVIRONMENT_SLOT, and SERVICE_SLOT. A task can retrieve the currently registered ports by using the mach_ports_lookup function.

Notes. When a new task is created (with task_create), the child task can inherit the parent's registered ports. Note that child tasks do not automatically acquire rights to these ports. They must use mach_ports_lookup to get them. It is intended that port registration be used only for task initialization, and then only by run-time support modules. A parent task has three choices when passing registered ports to child tasks: The parent task can do nothing. In this case, all child tasks inherit access to the same ports that the parent has. The parent task can use mach_ports_register to modify its set of registered ports before creating child tasks. In this case, the child tasks get access to the modified set of ports. After creating its child tasks. the parent can use mach_ports_register again to reset its registered ports. The parent task can first create a specific child task and then use mach_ports_register to modify the child's inherited set of ports, before starting the child's thread(s). The parent must specify the child's task port, rather than its own, on the call to mach_ports_register. Tasks other than the Name Server and the Environment Manager should not need access to the Service port. The Name Server port is the same for all tasks on a given machine. The Environment port is the only port likely to have different values for different tasks. Registered ports are restricted to those ports that are used by the run-time system to initialize a task. A parent task can pass other ports to its child tasks through: An initial message (see mach_msg). The Name Server, for public ports. The Environment Manager, for private ports. The task bootstrap port (see task_get_special_port).

The mach_ports_lookup function returns an array of the well-known system ports that are currently registered for the specified task. Note that the task holds only send rights for the ports. Registered ports are those ports that are used by the run-time system to initialize a task. To register system ports for a task, use the mach_ports_register function.

The task_info function returns an information structure of type flavor.

Notes. At any given time, a task has one default scheduling policy assigned to it (as returned by TASK_BASIC_INFO). As such, only one of the scheduling flavors will return valid information.

The task_set_info interface provides the caller with the means to set the target task's user_data field. This field may be used to specify arbitrarily task-specific data.

Notes. Currently, this interface is used exclusively to provide freshly colocated user tasks with the short-circuited RPC glue vector.

The task_suspend function increments the suspend count for task and stops all threads within the task. As long as the suspend count is positive, no newly-created threads can execute. The function does not return until all of the task's threads have been suspended.

Notes. To resume a suspended task and its threads, use task_resume. If the suspend count is greater than one, task_resume must be repeated that number of times.

The task_resume function decrements the suspend count for task. If the task's suspend count goes to zero, the function resumes any suspended threads within the task. To resume a given thread, the thread's own suspend count must also be zero.

Notes. An attempt to lower the suspend count below zero is ignored.

The task_get_special_port function returns a send right for a special port belonging to task. If one task has a send right for the kernel port of another task, it can use the port to perform kernel operations for the other task. Send rights for a kernel port normally are held only by the task to which the port belongs, or by the task's parent task. Using the mach_msg function, however, any task can pass a send right for its kernel port to another task.

Notes. The current implementation does not support the TASK_HOST_NAME_PORT features associated with this interface.

The task_set_special_port function sets a special port belonging to task.

Notes. The current implementation does not support the TASK_HOST_NAME_PORT features associated with this interface.

The thread_create function creates a new thread within parent_task. The new thread has a suspend count of one and no processor state. The new thread holds a send right for its thread kernel port. A send right for the thread's kernel port is also returned to the calling task or thread in child_thread. The new thread's exception ports are set to MACH_PORT_NULL.

Notes. To get a new thread running, first use thread_set_state to set a processor state for the thread. Then, use thread_resume to schedule the thread for execution. Alternately, use thread_create_running.

The thread_create_running function creates a new thread within parent_task. The new thread has is not suspended. Its initial state is given by state. flavor specifies the type of state to set. The format of the state to set is machine specific; it is defined in \*L \*O. The new thread holds a send right for its thread kernel port. A send right for the thread's kernel port is also returned to the calling task or thread in child_thread. The new thread's exception ports are set to MACH_PORT_NULL.

Notes. This is an optimized form of the sequence: thread_create, thread_set_state and thread_resume.

The task_set_exception_ports function sets a specified set of exception ports belonging to task. A task exception port is used when a thread specific exception port returns a non-success reply.

Notes. If the value of the EXC_MACH_SYSCALL exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception.

The task_get_exception_ports function returns send rights for a specified set of exception ports belonging to task. A task exception port is used when a thread specific exception port returns a non-success reply. The call returns a set of quadruples for each unique set of in effect for the task where the exception type mask indicates for which exception types the other values apply.

The task_swap_exception_ports function sets a specified set of exception ports belonging to task, returning the old set. A task exception port is used when a thread specific exception port returns a non-success reply.

Notes. If the value of the EXC_MACH_SYSCALL exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception.

The lock_set_create function creates a new lock set representing a collection of associated locks. The lock set is associated with the specified task. A send right naming the lock set is returned to the caller.

The lock_set_destroy function will destroy a lock set and all of its associated locks. Threads that are blocked on locks represented by the destroyed lock set are unblocked and will receive a KERN_LOCK_SET_DESTROYED error message indicating that the lock set was destroyed. The lock_set_destroy function will only succeed if the specified task is associated with the specified lock set.

The semaphore_create function creates a new semaphore, associates the created semaphore with the specified task, and returns a send right naming the new semaphore. In order to support a robust producer/consumer communication service, Interrupt Service Routines (ISR) must be able to signal semaphores. The semaphore synchronizer service is designed to allow user-level device drivers to perform signal operations, eliminating the need for event counters. Device drivers which utilize semaphores are responsible for creating (via semaphore_create) and exporting (via device_get_status) semaphores for user level access. Device driver semaphore creation is done at device initialization time. Device drivers may support multiple semaphores.

The semaphore_destroy function destroys a semaphore. All send rights naming the semaphore become dead names. Threads waiting on the semaphore become unblocked with the return from the semaphore_wait call indicating that the semaphore was destroyed. A call to semaphore_destroy succeeds only if the semaphore is associated with the specified task.

The task_sample function causes the program counter (PC) of the specified sample_task (actually, all of the threads within sample_task) to be sampled periodically (whenever one of the threads happens to be running at the time of the kernel's "hardclock" interrupt). The set of PC sample values obtained are saved in buffers which are sent to the specified reply_port in receive_samples messages.

The task_policy function sets the default scheduling attributes for task. These attributes are used when creating new threads. Changing the default attributes for a task does not affect the attributes of the contained threads unless change_threads is TRUE. At no time will a thread ever have scheduling attributes that exceed the thread's limits.

The task_set_emulation function establishes a handler within the task for a particular system call. When a thread executes a system call with this particular number, the system call will be redirected to the specified routine within the task's address space. This is expected to be an address within the transparent emulation library. These emulation handler addresses are inherited by child processes.

Notes. This interface is machine word length specific because of the virtual address parameter.

The task_get_emulation_vector function returns the user-level syscall handler entrypoint addresses.

Notes. This interface is machine word length specific because of the virtual addresses in the emulation_vector parameter.

The task_set_emulation_vector function establishes a handler within the task for a set of system calls. When a thread executes a system call with one of these numbers, the system call will be redirected to the corresponding routine within the task's address space. These emulation handler addresses are inherited by child processes.

Notes. This interface is machine word length specific because of the virtual addresses in the emulation_vector parameter.

The task_assign function assigns task to the set processor_set. After the assignment is completed, newly created threads within this task will be assigned to this processor set. Any previous assignment of the task is nullified. If assign_threads is TRUE, existing threads within the task will also be assigned to the processor set.

The task_assign_default function assigns task to the default processor set. After the assignment is completed, newly created threads within this task will be assigned to this processor set. Any previous assignment of the task is nullified. If assign_threads is TRUE, existing threads within the task will also be assigned to the processor set.

Notes. This variant of task_assign exists because the control port for the default processor set is privileged, and therefore not available to most tasks.

The task_get_assignment function returns the name port to the processor set to which task is currently assigned. This port can only be used to obtain information about the processor set.

The task_set_policy function sets the scheduling attributes, both base and limit, for task. policy may be any policy implemented by the processor set whether or not it is enabled.