From 053f7cff3c95acb915e6babfd306971f11bb7986 Mon Sep 17 00:00:00 2001 From: Benoit Germain Date: Sat, 5 Nov 2011 17:31:02 +0100 Subject: * process exit change: close everything at GC when main state closes, not when atexit() handlers are processed * Lua 5.2-style module: * module() is no longer used to implement lanes.lua * a global "lanes" variable is no longer created when the module is required * the Lanes module table is returned instead * Lanes must be initialized before used: * the first occurence of 'require "lanes"' produces a minimal interface that only contains a configure() function * the remainder of the interface is made available once this function is called * subsequent calls to configure() do nothing * configure() controls the number of keeper states and the startup of timers * LuaJIT 2 compatibility * non-Lua functions are no longer copied by creating a C closure from a C pointer, but through 2-way lookup tables * this means that if a lane function body pulls non-Lua functions, the lane generator description must contain the list of libraries and modules that exports them * introduces a change in configuration .globals management: contents are copied *after* std libs are loaded * new .required configuration entry to list modules that must be require()'ed before lane body is transferred * lane:cancel() wakes up waiting lindas like what is done at lane shutdown --- docs/index.html | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 107 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 3c4fe59..3c9abfe 100644 --- a/docs/index.html +++ b/docs/index.html @@ -54,9 +54,9 @@ Change log -


Copyright © 2007-11 Asko Kauppi. All rights reserved. +


Copyright © 2007-12 Asko Kauppi, Benoit Germain. All rights reserved.
Lua Lanes is published under the same MIT license as Lua 5.1. -

This document was revised on 1-Mar-11, and applies to version 2.1.0. +

This document was revised on 5-Nov-11, and applies to version 3.0-beta.

@@ -162,7 +162,51 @@ Or use Lua Rocks package m
-

Creation

+ +

Initialization

+ +

+ The following sample shows how to initialize the Lanes module. +

+ + + +
+ 
+          local lanes = require "lanes"
+          lanes.configure( 1)
+
+
+ +

+ Starting with version 3.0-beta, requiring the module follows Lua 5.2 rules: + the module is not available under the global name "lanes", but has to be accessed + through require's return value. + After lanes is required, it is necessary to call lanes.configure(), which is the + only function exposed by the module at this point. Calling configure() will + perform one-time initializations and make the rest of the API available. + At the same time, configure() itself will be replaced by another function that + raises an error if called with differing arguments. +

+ +

+ + +
+ + lanes.configure( [nb_keepers] [, "NO_TIMERS"]) + +
+

+

+ lanes.configure accepts 2 arguments. The first one controls the number + of keeper states used internally by lindas to transfer data between lanes. (see below). + Default is 1. +

+

If the second argument is equal to "NO_TIMERS", Lanes doesn't start the timer service, + and the associated API will be absent from the interface (see below). +

+

Creation

The following sample shows preparing a function for parallel calling, and calling it with varying arguments. Each of the two results is calculated in @@ -172,7 +216,8 @@ joins the threads, waiting for any results not already there. 
-  require "lanes"
+  local lanes = require "lanes"
+  lanes.configure( 1)
 
   f= lanes.gen( function(n) return 2*n end )
   a= f(1)
@@ -189,7 +234,7 @@ joins the threads, waiting for any results not already there.
     lane_h= func( ... )

-

+

The function returned by lanes.gen() is a "generator" for launching any number of lanes. They will share code, options, initial globals, but the particular arguments may vary. Only calling the generator function @@ -256,6 +301,23 @@ also in the new lanes. modifying one will only affect the particular lane. + + + + .required
modules_tbl + + + Lists modules that have to be required in order to be able to trasnfer + functions they exposed. Starting with Lanes 3.0-beta, non-Lua functions are + no longer copied by recreating a C closure from a C pointer, but are searched + in lookup tables. These tables are built from the modules listed here. required + must be a list of strings, each one being the name of a module to be required. +
+ The global values of different lanes are in no manner connected; + modifying one will only affect the particular lane. + + + .priority
-2..+2 The priority of lanes generated. -2 is lowest, +2 is highest. @@ -273,6 +335,7 @@ also in the new lanes. package.path and package.cpath overrides, if needed. Specifying these when libs_str doesn't cause the package library to be loaded will generate an error. + If not specified, the created lane will receive the current values of package.path and package.cpath.
@@ -407,8 +470,9 @@ OS thread running the lane is forcefully killed. This means no GC, and should generally be the last resort.

Cancellation is tested before going to sleep in receive() or send() calls -and after executing cancelstep Lua statements. A currently pending receive() -or send() call is currently not awakened, and may be a reason for a non-detected cancel. +and after executing cancelstep Lua statements. Starting with version 3.0-beta, a pending receive() +or send() call is awakened. This means the execution of the lane will resume although the operation has +not completed, to give the lane a chance to detect cancellation. The code should be able to handle this situation appropriately if required. It is also possible to manually test for cancel requests with cancel_test().

@@ -619,6 +683,8 @@ you want to use several?
  • Performance. Changing any slot in a Linda causes all pending threads for that Linda to be momentarily awakened (at least in the C level). This can degrade performance due to unnecessary OS level context switches. + The more keeper states you declared with lanes.configure() the less + this should be a problem.
    • @@ -639,6 +705,10 @@ events to a common Linda, but... :).     = lanes.timer( linda_h, key, date_tbl|first_secs [,period_secs] ) +

    + Timers are implemented as a lane. They can be disabled by passing "NO_TIMERS" + to lanes.configure(). +

    Timers can be run once, or in a reoccurring fashion (period_secs > 0). The first occurrence can be given either as a date or as a relative delay in seconds. @@ -655,7 +725,8 @@ A timer can be stopped simply by first_secs=0 and no period. 
    -  require "lanes"
+  local lanes = require "lanes"
+  lanes.configure( 1)
 
   local linda= lanes.linda()
 
@@ -991,11 +1062,37 @@ its actual value.
 
 
    
 
+  Nov-2011
+  
      
+    
    • process exit change: close everything at GC when main state closes, not when atexit() handlers are processed
      • 
+    
    • Lua 5.2-style module:
      • 
+    
        
+      
      • module() is no longer used to implement lanes.lua
        • 
+      
      • a global "lanes" variable is no longer created when the module is required
        • 
+      
      • the Lanes module table is returned instead
        • 
+    
      
+    
    • Lanes must be initialized before used:
      • 
+    
        
+      
      • the first occurence of 'require "lanes"' produces a minimal interface that only contains a configure() function
        • 
+      
      • the remainder of the interface is made available once this function is called
        • 
+      
      • subsequent calls to configure() do nothing
        • 
+      
      • configure() controls the number of keeper states and the startup of timers
        • 
+    
      
+    
    • * LuaJIT 2 compatibility
      • 
+    
        
+      
      • non-Lua functions are no longer copied by creating a C closure from a C pointer, but through 2-way lookup tables
        • 
+      
      • this means that if a lane function body pulls non-Lua functions, the lane generator description must contain the list of libraries and modules that exports them
        • 
+      
      • introduces a change in configuration .globals management: contents are copied *after* std libs are loaded
        • 
+      
      • new .required configuration entry to list modules that must be require()'ed before lane body is transferred
        • 
+    
      
+    
    • lane:cancel() wakes up waiting lindas like what is done at lane shutdown
      • 
+  
    
+
   Mar-2011 (not yet versioned)
   
      
     
    • linda honors __tostring and __concat
      • 
-    
    • new accessor linda:keys(), to retrieve the list of keys with pending data inside a linda
      • 
-    
    • new lanes options packagepath and packagecpath, in case one needs to set them differently than the default
      • 
+    
    • new accessor linda:count(), to get info about data stored inside a linda.
      • 
+    
    • new lanes options packagepath and packagecpath, in case one needs to set them differently than the default.
      • 
   
    
 
   Mar-2011 (2.1.0)
-- 
cgit v1.2.3-55-g6feb