release 1.0.0

Tieske · Jun 26, 2023 · 159bc6c · 159bc6c
1 parent f04a4bf
commit 159bc6c
Show file tree

Hide file tree

Showing 11 changed files with 173 additions and 26 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,25 @@
 # CHANGELOG
 
-### Version x.x, unreleased
+#### Releasing new versions
+
+- create a release branch
+- update the changelog below
+- update version and copyright-years in `./LICENSE` and `./src/copas/async.lua`
+  (in doc-comments header)
+- create a new rockspec and update the version inside the new rockspec:<br/>
+  `cp copas-async-scm-1.rockspec ./rockspecs/copas-async-X.Y.Z-1.rockspec`
+- test: run `make test` and `make lint`
+- clean and render the docs: run `make clean` and `make docs`
+- commit the changes as `release X.Y.Z`
+- push the commit, and create a release PR
+- after merging tag the release commit with `vX.Y.Z`
+- upload to LuaRocks:<br/>
+  `luarocks upload ./rockspecs/copas-async-X.Y.Z-1.rockspec --api-key=ABCDEFGH`
+- test the newly created rock:<br/>
+  `luarocks install copas-async`
+
+
+### Version 1.0.0, released 26-Jun-2023
 
 - Breaking: the `os_execute` return codes are no longer normalized to Lua 5.3 output
   since that didn't work due to platform and version differences. Now it just returns

diff --git a/LICENSE.md b/LICENSE.md
@@ -1,6 +1,6 @@
-The MIT License (MIT)
+# MIT License
 
-Copyright (c) 2016 Hisham Muhammad
+### Copyright (c) 2016 Hisham Muhammad, 2022-2023 Thijs Schreijer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/docs/examples/example-popen.lua.html b/docs/examples/example-popen.lua.html
@@ -42,7 +42,7 @@ <h2>Topics</h2>
 <ul class="">
   <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li>
   <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li>
-  <li><a href="../topics/LICENSE.md.html">LICENSE</a></li>
+  <li><a href="../topics/LICENSE.md.html">MIT License</a></li>
 </ul>
 
 </div>
@@ -118,7 +118,7 @@ <h2>example-popen.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-16 11:57:36 </i>
+<i style="float:right;">Last updated 2023-06-26 20:07:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

diff --git a/docs/examples/example.lua.html b/docs/examples/example.lua.html
@@ -42,7 +42,7 @@ <h2>Topics</h2>
 <ul class="">
   <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li>
   <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li>
-  <li><a href="../topics/LICENSE.md.html">LICENSE</a></li>
+  <li><a href="../topics/LICENSE.md.html">MIT License</a></li>
 </ul>
 
 </div>
@@ -120,7 +120,7 @@ <h2>example.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-16 11:57:36 </i>
+<i style="float:right;">Last updated 2023-06-26 20:07:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

diff --git a/docs/index.html b/docs/index.html
@@ -42,7 +42,7 @@ <h2>Topics</h2>
 <ul class="">
   <li><a href="topics/01-introduction.md.html">1. Introduction</a></li>
   <li><a href="topics/CHANGELOG.md.html">CHANGELOG</a></li>
-  <li><a href="topics/LICENSE.md.html">LICENSE</a></li>
+  <li><a href="topics/LICENSE.md.html">MIT License</a></li>
 </ul>
 <h2>Examples</h2>
 <ul class="nowrap">
@@ -59,9 +59,21 @@ <h1>Module <code>copas-async</code></h1>
 <p> When loaded this module will initialize LuaLanes by calling
  <code>lanes.configure()</code> without arguments. If you don't want/need that, then
  call <code>lanes.configure</code> before loading/requiring this module.</p>
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example">local async = require &quot;copas.async&quot;
+
+local function sometask()
+  -- do something that takes a while
+  return ok, err
+end
+
+local ok, err = async(sometask)
+</pre>
+    </ul>
     <h3>Info:</h3>
     <ul>
-        <li><strong>Copyright</strong>: Copyright (c) 2016 Hisham Muhammad</li>
+        <li><strong>Copyright</strong>: Copyright (c) 2016 Hisham Muhammad, 2022-2023 Thijs Schreijer</li>
         <li><strong>License</strong>: MIT, see <a href="topics/LICENSE.md.html#">LICENSE.md</a>.</li>
         <li><strong>Author</strong>: Hisham Muhammad</li>
     </ul>
@@ -94,6 +106,10 @@ <h2><a href="#Async_module">Async module </a></h2>
 	<td class="name" nowrap><a href="#async.os_execute">async.os_execute (command)</a></td>
 	<td class="summary">Convenience function that runs an os command in its own async thread.</td>
 	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#async.run">async.run (fn)</a></td>
+	<td class="summary">Runs a function in its own thread, and waits for the results.</td>
+	</tr>
 </table>
 
 <br/>
@@ -240,11 +256,11 @@ <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">command</span>
             <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         The command to pass to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-io.popen">io.popen</a> in the async thread.
+         The command to pass to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-io.popen">io.popen</a> in the async thread
         </li>
         <li><span class="parameter">mode</span>
             <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         The mode to pass to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-io.popen">io.popen</a> in the async thread.
+         The mode to pass to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-io.popen">io.popen</a> in the async thread
          (<em>default</em> "r")
         </li>
     </ul>
@@ -277,7 +293,7 @@ <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">command</span>
             <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         The command to pass to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-os.execute">os.execute</a> in the async thread.
+         The command to pass to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-os.execute">os.execute</a> in the async thread
         </li>
     </ul>
 
@@ -290,6 +306,45 @@ <h3>Returns:</h3>
 
 
 
+</dd>
+    <dt>
+    <a name = "async.run"></a>
+    <strong>async.run (fn)</strong>
+    </dt>
+    <dd>
+    Runs a function in its own thread, and waits for the results.
+ This will block the current thread, but will not block other Copas threads.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">fn</span>
+            <span class="types"><span class="type">function</span></span>
+         the function to execute async
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        the original functions return values
+    </ol>
+
+
+
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="comment">-- assuming a function returning a value or nil+error, normally called like this;
+</span><span class="comment">--
+</span><span class="comment">--   local result, err = fn()
+</span><span class="comment">--
+</span><span class="comment">-- Can be called non-blocking like this:
+</span>
+<span class="keyword">local</span> result, err = async.run(fn)
+<span class="comment">-- or even shorter;
+</span><span class="keyword">local</span> result, err = async(fn)</pre>
+    </ul>
+
 </dd>
 </dl>
 
@@ -298,7 +353,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-16 11:57:36 </i>
+<i style="float:right;">Last updated 2023-06-26 20:07:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

diff --git a/docs/topics/01-introduction.md.html b/docs/topics/01-introduction.md.html
@@ -27,13 +27,17 @@
 <h1>copas-async</h1>
 
 
+<h2>Contents</h2>
+<ul>
+<li><a href="#Installing">Installing </a></li>
+</ul>
 
 
 <h2>Topics</h2>
 <ul class="">
   <li><strong>1. Introduction</strong></li>
   <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li>
-  <li><a href="../topics/LICENSE.md.html">LICENSE</a></li>
+  <li><a href="../topics/LICENSE.md.html">MIT License</a></li>
 </ul>
 <h2>Modules</h2>
 <ul class="nowrap">
@@ -56,7 +60,8 @@ <h1>1. Introduction</h1>
 
 <p><strong>This is alpha software, use at your own peril!</strong></p>
 
-<p>1.1 Installing</p>
+<p><a name="Installing"></a></p>
+<h2>Installing</h2>
 
 
 <pre>
@@ -69,7 +74,7 @@ <h1>1. Introduction</h1>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-16 11:57:36 </i>
+<i style="float:right;">Last updated 2023-06-26 20:07:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

diff --git a/docs/topics/CHANGELOG.md.html b/docs/topics/CHANGELOG.md.html
@@ -33,7 +33,7 @@ <h2>Topics</h2>
 <ul class="">
   <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li>
   <li><strong>CHANGELOG</strong></li>
-  <li><a href="../topics/LICENSE.md.html">LICENSE</a></li>
+  <li><a href="../topics/LICENSE.md.html">MIT License</a></li>
 </ul>
 <h2>Modules</h2>
 <ul class="nowrap">
@@ -52,7 +52,28 @@ <h2>Examples</h2>
 
 <h1>CHANGELOG</h1>
 
-<h3>Version x.x, unreleased</h3>
+<h4>Releasing new versions</h4>
+
+<ul>
+    <li>create a release branch</li>
+    <li>update the changelog below</li>
+    <li>update version and copyright-years in <code>./LICENSE</code> and <code>./src/copas/async.lua</code>
+    (in doc-comments header)</li>
+    <li>create a new rockspec and update the version inside the new rockspec:<br/>
+    <code>cp copas-async-scm-1.rockspec ./rockspecs/copas-async-X.Y.Z-1.rockspec</code></li>
+    <li>test: run <code>make test</code> and <code>make lint</code></li>
+    <li>clean and render the docs: run <code>make clean</code> and <code>make docs</code></li>
+    <li>commit the changes as <code>release X.Y.Z</code></li>
+    <li>push the commit, and create a release PR</li>
+    <li>after merging tag the release commit with <code>vX.Y.Z</code></li>
+    <li>upload to LuaRocks:<br/>
+    <code>luarocks upload ./rockspecs/copas-async-X.Y.Z-1.rockspec --api-key=ABCDEFGH</code></li>
+    <li>test the newly created rock:<br/>
+    <code>luarocks install copas-async</code></li>
+</ul>
+
+
+<h3>Version 1.0.0, released 26-Jun-2023</h3>
 
 <ul>
     <li>Breaking: the <a href="../index.html#async.os_execute">os_execute</a> return codes are no longer normalized to Lua 5.3 output
@@ -64,6 +85,8 @@ <h3>Version x.x, unreleased</h3>
     <li>Fix: only initialize LuaLanes if not initialized already</li>
     <li>Added: <a href="../index.html#async.io_popen">io_popen</a> now also has the <code>lines</code> iterator (except for Puc Rio Lua 5.1
     where it will not work due to c-boundary issues)</li>
+    <li>Added: <a href="../index.html#async.run">run</a> method, to simply run and wait for an async result while not blocking
+    (this also is the default action when calling on the module table).</li>
 </ul>
 
 <h3>Version 0.3, released 4-Jul-2016</h3>
@@ -89,7 +112,7 @@ <h3>Version 0.1, released 2-Jun-2016</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-16 11:57:36 </i>
+<i style="float:right;">Last updated 2023-06-26 20:07:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

diff --git a/docs/topics/LICENSE.md.html b/docs/topics/LICENSE.md.html
@@ -33,7 +33,7 @@ <h2>Topics</h2>
 <ul class="">
   <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li>
   <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li>
-  <li><strong>LICENSE</strong></li>
+  <li><strong>MIT License</strong></li>
 </ul>
 <h2>Modules</h2>
 <ul class="nowrap">
@@ -49,9 +49,10 @@ <h2>Examples</h2>
 
 <div id="content">
 
-    The MIT License (MIT)</p>
 
-<p>Copyright (c) 2016 Hisham Muhammad</p>
+<h1>MIT License</h1>
+
+<h3>Copyright (c) 2016 Hisham Muhammad, 2022-2023 Thijs Schreijer</h3>
 
 <p>Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -69,13 +70,14 @@ <h2>Examples</h2>
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.</p>
+
 
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2023-02-16 11:57:36 </i>
+<i style="float:right;">Last updated 2023-06-26 20:07:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

diff --git a/rockspecs/copas-async-1.0.0-1.rockspec b/rockspecs/copas-async-1.0.0-1.rockspec
@@ -0,0 +1,43 @@
+local package_name = "copas-async"
+local package_version = "1.0.0"
+local rockspec_revision = "1"
+local github_account_name = "Tieske"
+local github_repo_name = "copas-async"
+
+
+package = package_name
+version = package_version.."-"..rockspec_revision
+
+source = {
+   url = "git+https://github.com/"..github_account_name.."/"..github_repo_name..".git",
+   branch = (package_version == "scm") and "master" or nil,
+   tag = (package_version ~= "scm") and ("v"..package_version) or nil,
+}
+
+description = {
+   summary = "Copas add-on to provide true asynchronus threads",
+   detailed = [[
+      Copas-friendly true asynchronous threads, powered by Lua Lanes.
+   ]],
+   license = "MIT",
+   homepage = "https://github.com/"..github_account_name.."/"..github_repo_name,
+}
+
+dependencies = {
+   "lua >= 5.1",
+   "lanes >= 3.10.0",
+   "copas >= 2.0.2",
+}
+
+build = {
+   type = "builtin",
+
+   modules = {
+      ["copas.async"] = "src/copas/async.lua",
+   },
+
+   copy_directories = {
+      "docs",
+   },
+}
+
diff --git a/spec/async_spec.lua b/spec/async_spec.lua
@@ -87,7 +87,7 @@ describe("copas-async", function()
       end)
 
 
-      it("cocurrent access to future errors", function()
+      it("concurrent access to future errors", function()
          local result = {}
          copas(function()
             local future = async.addthread(assert(load([[

diff --git a/src/copas/async.lua b/src/copas/async.lua
@@ -5,7 +5,7 @@
 -- `lanes.configure()` without arguments. If you don't want/need that, then
 -- call `lanes.configure` before loading/requiring this module.
 --
--- @copyright Copyright (c) 2016 Hisham Muhammad
+-- @copyright Copyright (c) 2016 Hisham Muhammad, 2022-2023 Thijs Schreijer
 -- @author Hisham Muhammad
 -- @license MIT, see `LICENSE.md`.
 -- @name copas-async