<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>Stopping Safely</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="The utrace User Debugging Infrastructure" /><link rel="up" href="ch01.html" title="Chapter 1. utrace concepts" /><link rel="prev" href="ch01s02.html" title="Events and Callbacks" /><link rel="next" href="ch01s04.html" title="Tear-down Races" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Stopping Safely</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01s02.html">Prev</a> </td><th width="60%" align="center">Chapter 1. utrace concepts</th><td width="20%" align="right"> <a accesskey="n" href="ch01s04.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Stopping Safely"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="safely"></a>Stopping Safely</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="ch01s03.html#well-behaved">Writing well-behaved callbacks</a></span></dt><dt><span class="sect2"><a href="ch01s03.html#UTRACE_STOP">Using <code class="constant">UTRACE_STOP</code></a></span></dt></dl></div><div class="sect2" title="Writing well-behaved callbacks"><div class="titlepage"><div><div><h3 class="title"><a id="well-behaved"></a>Writing well-behaved callbacks</h3></div></div></div><p> Well-behaved callbacks are important to maintain two essential properties of the interface. The first of these is that unrelated tracing engines should not interfere with each other. If your engine's event callback does not return quickly, then another engine won't get the event notification in a timely manner. The second important property is that tracing should be as noninvasive as possible to the normal operation of the system overall and of the traced thread in particular. That is, attached tracing engines should not perturb a thread's behavior, except to the extent that changing its user-visible state is explicitly what you want to do. (Obviously some perturbation is unavoidable, primarily timing changes, ranging from small delays due to the overhead of tracing, to arbitrary pauses in user code execution when a user stops a thread with a debugger for examination.) Even when you explicitly want the perturbation of making the traced thread block, just blocking directly in your callback has more unwanted effects. For example, the <code class="constant">CLONE</code> event callbacks are called when the new child thread has been created but not yet started running; the child can never be scheduled until the <code class="constant">CLONE</code> tracing callbacks return. (This allows engines tracing the parent to attach to the child.) If a <code class="constant">CLONE</code> event callback blocks the parent thread, it also prevents the child thread from running (even to process a <code class="constant">SIGKILL</code>). If what you want is to make both the parent and child block, then use <code class="function">utrace_attach_task</code> on the child and then use <code class="constant">UTRACE_STOP</code> on both threads. A more crucial problem with blocking in callbacks is that it can prevent <code class="constant">SIGKILL</code> from working. A thread that is blocking due to <code class="constant">UTRACE_STOP</code> will still wake up and die immediately when sent a <code class="constant">SIGKILL</code>, as all threads should. Relying on the <span class="application">utrace</span> infrastructure rather than on private synchronization calls in event callbacks is an important way to help keep tracing robustly noninvasive. </p></div><div class="sect2" title="Using UTRACE_STOP"><div class="titlepage"><div><div><h3 class="title"><a id="UTRACE_STOP"></a>Using <code class="constant">UTRACE_STOP</code></h3></div></div></div><p> To control another thread and access its state, it must be stopped with <code class="constant">UTRACE_STOP</code>. This means that it is stopped and won't start running again while we access it. When a thread is not already stopped, <code class="function">utrace_control</code> returns <code class="constant">-EINPROGRESS</code> and an engine must wait for an event callback when the thread is ready to stop. The thread may be running on another CPU or may be blocked. When it is ready to be examined, it will make callbacks to engines that set the <code class="constant">UTRACE_EVENT(QUIESCE)</code> event bit. To wake up an interruptible wait, use <code class="constant">UTRACE_INTERRUPT</code>. </p><p> As long as some engine has used <code class="constant">UTRACE_STOP</code> and not called <code class="function">utrace_control</code> to resume the thread, then the thread will remain stopped. <code class="constant">SIGKILL</code> will wake it up, but it will not run user code. When the stop is cleared with <code class="function">utrace_control</code> or a callback return value, the thread starts running again. (See also <a class="xref" href="ch01s04.html" title="Tear-down Races">the section called “Tear-down Races”</a>.) </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch01s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Events and Callbacks </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Tear-down Races</td></tr></table></div></body></html>