osfmk/man/thread_activation_create.html

   1 <h2>thread_activation_create</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Create a thread activation.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   thread_activation_create</strong>
   8                 <strong>(task_t</strong>                                    <var>task</var>,
   9                  <strong>mach_port_name_t</strong>                      <var>RPC_port</var>,
  10                  <strong>vm_offset_t</strong>                         <var>user_stack</var>,
  11                  <strong>vm_size_t</strong>                           <var>stack_size</var>,
  12                  <strong>thread_act_t</strong>                      <var>thread_act_t</var><strong>);</strong>
  13 </pre>
  14 <h3>PARAMETERS</h3>
  15 <dl>
  16 <p>
  17 <dt> <var>task</var>
  18 <dd>
  19 [in task send right] The port for the task that is to contain the new
  20 thread activation.
  21 <p>
  22 <dt> <var>RPC_port</var>
  23 <dd>
  24 [in receive right] A receive right held by the task, or a port set in the
  25 task.
  26 <p>
  27 <dt> <var>user_stack</var>
  28 <dd>
  29 [in scalar] The virtual address in the task to be used as the starting ad-
  30 dress of the user-level stack.
  31 <p>
  32 <dt> <var>new_act</var>
  33 <dd>
  34 [out thread send right] The kernel-assigned name for the new thread ac-
  35 tivation.
  36 </dl>
  37 <h3>DESCRIPTION</h3>
  38 <p>
  39 The thread_activation_create function creates a thread activation, or
  40 "empty thread", into which a client thread shuttle can migrate during
  41 RPC.  The RPC_port must name ei- ther a receive right held by the
  42 task, or a port set in the task.  The new thread activation will be
  43 added to a pool of activations attached to this port (or port set).
  44 Incoming RPC's targeted at the port (or one of the ports in the set)
  45 can use any of the activations in the pool.  That is, the client
  46 thread shuttle will migrate into the specified server task, take one
  47 of the thread activations out of the pool, and join up with it for the
  48 duration of the RPC.  The shuttle will migrate back to the original
  49 client activation at the end of the RPC.  If no thread activations are
  50 in the pool, RPC will be blocked until one is created in the pool, or
  51 an existing one finishes its RPC and returns to the pool.
  52 The new thread activation will begin each RPC using the stack pointer
  53 specified by user_stack.  The kernel neither knows nor cares how big
  54 the specified stack is.
  55 When a short-circuited RPC (or mach_rpc) is invoked on a port created
  56 with mach_port_allocate_subsystem, the RPC will begin execution in the
  57 subsystem server at the work function address specified by the port
  58 and routine number and looked up in the associated subsystem data.
  59 <h3>NOTES</h3>
  60 <p>
  61 The following calls targeted at a thread_act port may _not_ be called
  62 on an empty thread_act (and will return KERN_INVALID_ARGUMENT if
  63 they are called with one):
  64 thread_abort
  65 thread_abort_safely
  66 thread_depress_abort
  67 thread_info
  68 thread_wire
  69 In addition, if thread_switch is called with an empty thread_act as
  70 its first argument, the argument will be ignored (i.e., the function
  71 will behave as if a zero-valued argument had been given).
  72 <h3>RETURN VALUES</h3>
  73 <p>
  74 Only generic errors apply.
  75 <h3>RELATED INFORMATION</h3>
  76 <p>
  77 Functions:
  78 <a href="task_create.html"><strong>task_create</strong></a>,
  79 <a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>,