📄 shared.html
字号:
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../displayToc.js"></script>
<script language="JavaScript" src="../../tocParas.js"></script>
<script language="JavaScript" src="../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../scineplex.css">
<title>threads::shared - Perl extension for sharing data structures between threads</title>
<link rel="stylesheet" href="../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<script>writelinks('__top__',2);</script>
<h1><a>threads::shared - Perl extension for sharing data structures between threads</a></h1>
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#version">VERSION</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#export">EXPORT</a></li>
<li><a href="#functions">FUNCTIONS</a></li>
<li><a href="#objects">OBJECTS</a></li>
<li><a href="#notes">NOTES</a></li>
<li><a href="#bugs_and_limitations">BUGS AND LIMITATIONS</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>threads::shared - Perl extension for sharing data structures between threads</p>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>This document describes threads::shared version 1.01</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
<span class="keyword">use</span> <span class="variable">threads</span><span class="operator">;</span>
<span class="keyword">use</span> <span class="variable">threads::shared</span><span class="operator">;</span>
</pre>
<pre>
<span class="keyword">my</span> <span class="variable">$var</span> <span class="operator">:</span><span class="variable">shared</span><span class="operator">;</span>
<span class="variable">$var</span> <span class="operator">=</span> <span class="variable">$scalar_value</span><span class="operator">;</span>
<span class="variable">$var</span> <span class="operator">=</span> <span class="variable">$shared_ref_value</span><span class="operator">;</span>
<span class="variable">$var</span> <span class="operator">=</span> <span class="variable">share</span><span class="operator">(</span><span class="variable">$simple_unshared_ref_value</span><span class="operator">);</span>
</pre>
<pre>
<span class="keyword">my</span><span class="operator">(</span><span class="variable">$scalar</span><span class="operator">,</span> <span class="variable">@array</span><span class="operator">,</span> <span class="variable">%hash</span><span class="operator">);</span>
<span class="variable">share</span><span class="operator">(</span><span class="variable">$scalar</span><span class="operator">);</span>
<span class="variable">share</span><span class="operator">(</span><span class="variable">@array</span><span class="operator">);</span>
<span class="variable">share</span><span class="operator">(</span><span class="variable">%hash</span><span class="operator">);</span>
<span class="keyword">my</span> <span class="variable">$bar</span> <span class="operator">=</span> <span class="operator">&</span><span class="variable">share</span><span class="operator">(</span><span class="operator">[]</span><span class="operator">);</span>
<span class="variable">$hash</span><span class="operator">{</span><span class="string">bar</span><span class="operator">}</span> <span class="operator">=</span> <span class="operator">&</span><span class="variable">share</span><span class="operator">(</span><span class="operator">{}</span><span class="operator">);</span>
</pre>
<pre>
<span class="operator">{</span> <span class="keyword">lock</span><span class="operator">(</span><span class="variable">%hash</span><span class="operator">);</span> <span class="operator">...</span> <span class="operator">}</span>
</pre>
<pre>
<span class="variable">cond_wait</span><span class="operator">(</span><span class="variable">$scalar</span><span class="operator">);</span>
<span class="variable">cond_timedwait</span><span class="operator">(</span><span class="variable">$scalar</span><span class="operator">,</span> <span class="keyword">time</span><span class="operator">()</span> <span class="operator">+</span> <span class="number">30</span><span class="operator">);</span>
<span class="variable">cond_broadcast</span><span class="operator">(</span><span class="variable">@array</span><span class="operator">);</span>
<span class="variable">cond_signal</span><span class="operator">(</span><span class="variable">%hash</span><span class="operator">);</span>
</pre>
<pre>
<span class="keyword">my</span> <span class="variable">$lockvar</span> <span class="operator">:</span><span class="variable">shared</span><span class="operator">;</span>
<span class="comment"># condition var != lock var</span>
<span class="variable">cond_wait</span><span class="operator">(</span><span class="variable">$var</span><span class="operator">,</span> <span class="variable">$lockvar</span><span class="operator">);</span>
<span class="variable">cond_timedwait</span><span class="operator">(</span><span class="variable">$var</span><span class="operator">,</span> <span class="keyword">time</span><span class="operator">()+</span><span class="number">30</span><span class="operator">,</span> <span class="variable">$lockvar</span><span class="operator">);</span>
</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>By default, variables are private to each thread, and each newly created
thread gets a private copy of each existing variable. This module allows you
to share variables across different threads (and pseudoforks on Win32). It is
used together with the <a href="../../lib/threads.html">the threads manpage</a> module.</p>
<p>
</p>
<hr />
<h1><a name="export">EXPORT</a></h1>
<p><a href="#item_share"><code>share</code></a>, <a href="#item_cond_wait"><code>cond_wait</code></a>, <code>cond_timedwait</code>, <a href="#item_cond_signal"><code>cond_signal</code></a>, <a href="#item_cond_broadcast"><code>cond_broadcast</code></a>,
<a href="#item_is_shared"><code>is_shared</code></a></p>
<p>Note that if this module is imported when <a href="../../lib/threads.html">the threads manpage</a> has not yet been loaded,
then these functions all become no-ops. This makes it possible to write
modules that will work in both threaded and non-threaded environments.</p>
<p>
</p>
<hr />
<h1><a name="functions">FUNCTIONS</a></h1>
<dl>
<dt><strong><a name="item_share">share VARIABLE</a></strong>
<dd>
<p><a href="#item_share"><code>share</code></a> takes a value and marks it as shared. You can share a scalar, array,
hash, scalar ref, array ref, or hash ref. <a href="#item_share"><code>share</code></a> will return the shared
rvalue, but always as a reference.</p>
</dd>
<dd>
<p>A variable can also be marked as shared at compile time by using the
<code>:shared</code> attribute: <code>my $var :shared;</code>.</p>
</dd>
<dd>
<p>Due to problems with Perl's prototyping, if you want to share a newly created
reference, you need to use the <a href="#item_share"><code>&share([])</code></a> and <a href="#item_share"><code>&share({})</code></a> syntax.</p>
</dd>
<dd>
<p>The only values that can be assigned to a shared scalar are other scalar
values, or shared refs:</p>
</dd>
<dd>
<pre>
<span class="keyword">my</span> <span class="variable">$var</span> <span class="operator">:</span><span class="variable">shared</span><span class="operator">;</span>
<span class="variable">$var</span> <span class="operator">=</span> <span class="number">1</span><span class="operator">;</span> <span class="comment"># ok</span>
<span class="variable">$var</span> <span class="operator">=</span> <span class="operator">[]</span><span class="operator">;</span> <span class="comment"># error</span>
<span class="variable">$var</span> <span class="operator">=</span> <span class="operator">&</span><span class="variable">share</span><span class="operator">(</span><span class="operator">[]</span><span class="operator">);</span> <span class="comment"># ok</span>
</pre>
</dd>
<dd>
<p><a href="#item_share"><code>share</code></a> will traverse up references exactly <em>one</em> level. <a href="#item_share"><code>share(\$a)</code></a> is
equivalent to <a href="#item_share"><code>share($a)</code></a>, while <a href="#item_share"><code>share(\\$a)</code></a> is not. This means that you
must create nested shared data structures by first creating individual shared
leaf nodes, and then adding them to a shared hash or array.</p>
</dd>
<dd>
<pre>
<span class="keyword">my</span> <span class="variable">%hash</span> <span class="operator">:</span><span class="variable">shared</span><span class="operator">;</span>
<span class="variable">$hash</span><span class="operator">{</span><span class="string">'meaning'</span><span class="operator">}</span> <span class="operator">=</span> <span class="operator">&</span><span class="variable">share</span><span class="operator">(</span><span class="operator">[]</span><span class="operator">);</span>
<span class="variable">$hash</span><span class="operator">{</span><span class="string">'meaning'</span><span class="operator">}[</span><span class="number">0</span><span class="operator">]</span> <span class="operator">=</span> <span class="operator">&</span><span class="variable">share</span><span class="operator">(</span><span class="operator">{}</span><span class="operator">);</span>
<span class="variable">$hash</span><span class="operator">{</span><span class="string">'meaning'</span><span class="operator">}[</span><span class="number">0</span><span class="operator">]</span><span class="operator">{</span><span class="string">'life'</span><span class="operator">}</span> <span class="operator">=</span> <span class="number">42</span><span class="operator">;</span>
</pre>
</dd>
</li>
<dt><strong><a name="item_is_shared">is_shared VARIABLE</a></strong>
<dd>
<p><a href="#item_is_shared"><code>is_shared</code></a> checks if the specified variable is shared or not. If shared,
returns the variable's internal ID (similar to
<a href="../../lib/Scalar/Util.html#refaddr_expr">refaddr()</a>). Otherwise, returns <a href="../../lib/Pod/perlfunc.html#item_undef"><code>undef</code></a>.</p>
</dd>
<dd>
<pre>
<span class="keyword">if</span> <span class="operator">(</span><span class="variable">is_shared</span><span class="operator">(</span><span class="variable">$var</span><span class="operator">))</span> <span class="operator">{</span>
<span class="keyword">print</span><span class="operator">(</span><span class="string">"\$var is shared\n"</span><span class="operator">);</span>
<span class="operator">}</span> <span class="keyword">else</span> <span class="operator">{</span>
<span class="keyword">print</span><span class="operator">(</span><span class="string">"\$var is not shared\n"</span><span class="operator">);</span>
<span class="operator">}</span>
</pre>
</dd>
</li>
<dt><strong><a name="item_lock">lock VARIABLE</a></strong>
<dd>
<p><a href="#item_lock"><code>lock</code></a> places a lock on a variable until the lock goes out of scope. If the
variable is locked by another thread, the <a href="#item_lock"><code>lock</code></a> call will block until it's
available. <a href="#item_lock"><code>lock</code></a> is recursive, so multiple calls to <a href="#item_lock"><code>lock</code></a> are safe -- the
variable will remain locked until the outermost lock on the variable goes out
of scope.</p>
</dd>
<dd>
<p>If a container object, such as a hash or array, is locked, all the elements of
that container are not locked. For example, if a thread does a <code>lock @a</code>,
any other thread doing a <a href="#item_lock"><code>lock($a[12])</code></a> won't block.</p>
</dd>
<dd>
<p><a href="#item_lock"><code>lock</code></a> will traverse up references exactly <em>one</em> level. <a href="#item_lock"><code>lock(\$a)</code></a> is
equivalent to <a href="#item_lock"><code>lock($a)</code></a>, while <a href="#item_lock"><code>lock(\\$a)</code></a> is not.</p>
</dd>
<dd>
<p>Note that you cannot explicitly unlock a variable; you can only wait for the
lock to go out of scope. This is most easily accomplished by locking the
variable inside a block.</p>
</dd>
<dd>
<pre>
<span class="keyword">my</span> <span class="variable">$var</span> <span class="operator">:</span><span class="variable">shared</span><span class="operator">;</span>
<span class="operator">{</span>
<span class="keyword">lock</span><span class="operator">(</span><span class="variable">$var</span><span class="operator">);</span>
<span class="comment"># $var is locked from here to the end of the block</span>
<span class="operator">...</span>
<span class="operator">}</span>
<span class="comment"># $var is now unlocked</span>
</pre>
</dd>
<dd>
<p>If you need more fine-grained control over shared variable access, see
<a href="../../lib/Thread/Semaphore.html">the Thread::Semaphore manpage</a>.</p>
</dd>
</li>
<dt><strong><a name="item_cond_wait">cond_wait VARIABLE</a></strong>
<dt><strong>cond_wait CONDVAR, LOCKVAR</strong>
<dd>
<p>The <a href="#item_cond_wait"><code>cond_wait</code></a> function takes a <strong>locked</strong> variable as a parameter, unlocks
the variable, and blocks until another thread does a <a href="#item_cond_signal"><code>cond_signal</code></a> or
<a href="#item_cond_broadcast"><code>cond_broadcast</code></a> for that same locked variable. The variable that
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -