<?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>
