range-lock 0.2.2

<div id="range-lock-multithread-range-lock-for-vec">
<h2>range-lock - Multithread range lock for Vec</h2>
<p><a href="https://bues.ch/" rel="nofollow">https://bues.ch/</a></p>
<p><a href="https://bues.ch/cgit/rangelockrs.git" rel="nofollow">https://bues.ch/cgit/rangelockrs.git</a></p>
<p>This crate provides locks/mutexes for multi-threaded access to a single Vec&lt;T&gt; instance.</p>
<p>Any thread can request exclusive access to a slice of the Vec.
Such access is granted, if no other thread is simultaneously holding the permission to access an overlapping slice.</p>
</div>
<div id="usage">
<h2>Usage</h2>
<p>Add this to your Cargo.toml:</p>
<pre><span class="k">[dependencies]</span><span class="w">
</span><span class="n">range-lock</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;0.2&quot;</span>
</pre>
<div id="vecrangelock-example-usage">
<h3>VecRangeLock example usage</h3>
<p>General purpose VecRangeLock:</p>
<pre><span class="k">use</span><span class="w"> </span><span class="n">range_lock</span>::<span class="n">VecRangeLock</span><span class="p">;</span><span class="w">
</span><span class="k">use</span><span class="w"> </span><span class="n">std</span>::<span class="n">sync</span>::<span class="n">Arc</span><span class="p">;</span><span class="w">
</span><span class="k">use</span><span class="w"> </span><span class="n">std</span>::<span class="n">thread</span><span class="p">;</span><span class="w">

</span><span class="kd">let</span><span class="w"> </span><span class="n">lock</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Arc</span>::<span class="n">new</span><span class="p">(</span><span class="n">VecRangeLock</span>::<span class="n">new</span><span class="p">(</span><span class="fm">vec!</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">]));</span><span class="w">

</span><span class="n">thread</span>::<span class="n">spawn</span><span class="p">(</span><span class="k">move</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="kd">let</span><span class="w"> </span><span class="k">mut</span><span class="w"> </span><span class="n">guard</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">lock</span><span class="p">.</span><span class="n">try_lock</span><span class="p">(</span><span class="mi">2</span><span class="o">..</span><span class="mi">4</span><span class="p">).</span><span class="n">expect</span><span class="p">(</span><span class="s">&quot;Failed to lock range 2..4&quot;</span><span class="p">);</span><span class="w">
    </span><span class="fm">assert_eq!</span><span class="p">(</span><span class="n">guard</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span><span class="w">
    </span><span class="n">guard</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">10</span><span class="p">;</span><span class="w">
</span><span class="p">});</span>
</pre>
</div>
<div id="repvecrangelock-example-usage">
<h3>RepVecRangeLock example usage</h3>
<p>The RepVecRangeLock is a restricted range lock, that provides access to interleaved patterns of slices to the threads.</p>
<p>Locking a RepVecRangeLock is more lightweight than locking a VecRangeLock.
The threads can not freely choose slice ranges, but only choose a repeating slice pattern by specifying a pattern offset.</p>
<p>Please see the example below.</p>
<pre><span class="k">use</span><span class="w"> </span><span class="n">range_lock</span>::<span class="n">RepVecRangeLock</span><span class="p">;</span><span class="w">
</span><span class="k">use</span><span class="w"> </span><span class="n">std</span>::<span class="n">sync</span>::<span class="n">Arc</span><span class="p">;</span><span class="w">
</span><span class="k">use</span><span class="w"> </span><span class="n">std</span>::<span class="n">thread</span><span class="p">;</span><span class="w">

</span><span class="kd">let</span><span class="w"> </span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="fm">vec!</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w">  </span><span class="c1">// &lt;- cycle 0
</span><span class="w">                </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">];</span><span class="w"> </span><span class="c1">// &lt;- cycle 1
//              ^  ^  ^
//              |  |  |
//              |  |  offset-2
//       offset-0  offset-1
</span><span class="w">
</span><span class="kd">let</span><span class="w"> </span><span class="n">lock</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Arc</span>::<span class="n">new</span><span class="p">(</span><span class="n">RepVecRangeLock</span>::<span class="n">new</span><span class="p">(</span><span class="n">data</span><span class="p">,</span><span class="w">
                                         </span><span class="mi">1</span><span class="p">,</span><span class="w">    </span><span class="c1">// slice_len: Each slice has 1 element.
</span><span class="w">                                         </span><span class="mi">3</span><span class="p">));</span><span class="w">  </span><span class="c1">// cycle_len: Each cycle has 3 slices (offsets).
</span><span class="n">thread</span>::<span class="n">spawn</span><span class="p">(</span><span class="k">move</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="c1">// Lock slice offset 1:
</span><span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="k">mut</span><span class="w"> </span><span class="n">guard</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">lock</span><span class="p">.</span><span class="n">try_lock</span><span class="p">(</span><span class="mi">1</span><span class="p">).</span><span class="n">expect</span><span class="p">(</span><span class="s">&quot;Failed to lock offset.&quot;</span><span class="p">);</span><span class="w">

    </span><span class="fm">assert_eq!</span><span class="p">(</span><span class="n">guard</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">0</span><span class="p">],</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w">     </span><span class="c1">// Cycle 0, Slice element 0
</span><span class="w">    </span><span class="fm">assert_eq!</span><span class="p">(</span><span class="n">guard</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">0</span><span class="p">],</span><span class="w"> </span><span class="mi">5</span><span class="p">);</span><span class="w">     </span><span class="c1">// Cycle 1, Slice element 0
</span><span class="w">
    </span><span class="n">guard</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">20</span><span class="p">;</span><span class="w">               </span><span class="c1">// Cycle 0, Slice element 0
</span><span class="w">    </span><span class="n">guard</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">50</span><span class="p">;</span><span class="w">               </span><span class="c1">// Cycle 1, Slice element 0
</span><span class="p">});</span>
</pre>
</div>
</div>
<div id="todos-for-future-releases">
<h2>TODOs for future releases</h2>
<p>The following new features might be candidates for future releases:</p>
<ul>
<li>Optimize the range overlap search algorithm.</li>
<li>Sleeping lock, in case of lock contention.</li>
<li>Add support for arrays.</li>
</ul>
</div>
<div id="license">
<h2>License</h2>
<p>Copyright (c) 2021-2022 Michael Buesch &lt;<a href="mailto:m&#37;&#52;&#48;bues&#46;ch">m<span>&#64;</span>bues<span>&#46;</span>ch</a>&gt;</p>
<p>Licensed under the Apache License version 2.0 or the MIT license, at your option.</p>
</div>