From 1843a0add00186eee129b0b0a2ee605866acbb61 Mon Sep 17 00:00:00 2001 From: Benoit Germain Date: Thu, 16 Jan 2014 14:17:23 +0100 Subject: Cancellation improvements and some fixes * bumped version to 3.7.8 * lane:cancel() now accepts a boolean second argument when soft cancelling (negative timeout) to wake the thread if necessary * if a blocked linda send() or receive() call is interrupted by a cancellation request, it returns CANCEL_ERROR so that this case can be differentiated from a simple timeout * fixed WIN32 THREAD_CREATE() wrong _beginthreadex() error detection * fatal WIN32 threading errors retrieve and output the error description string with FormatMessage() * fixed missing lanes.set_singlethreaded * fixed perftest.lua * added test/cancel.lua --- docs/index.html | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index c62f64f..3b64cb4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -70,7 +70,7 @@

- This document was revised on 09-Jan-14, and applies to version 3.7.7. + This document was revised on 16-Jan-14, and applies to version 3.7.8.

@@ -880,13 +880,18 @@

Cancelling

-	bool[,reason] = lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool = false] [, forcekill_timeout=0.0])
+	bool[,reason] = lane_h:cancel( [positive_timeout_secs=0.0] [, force_kill_bool = false] [, forcekill_timeout=0.0])
+	bool[,reason] = lane_h:cancel( negative_timeout_secs [, wake_bool = false])

cancel() sends a cancellation request to the lane.
- If timeout_secs is negative (aka "soft cancel"), starting with version 3.6.3, will only cause cancel_test() to return true, so that the lane can cleanup manually (the actual value is irrelevant). You can't provide the additional arguments in that case.
- If timeout_secs is positive (aka "hard cancel"), waits for the request to be processed, or a timeout to occur.
+ First argument is a timeout, that defaults to 0 if not specified. (Starting with version 3.6.3) signification of the following arguments differ depending on whether the timeout is negative or not. +
+ If timeout_secs is negative (aka "soft cancel"), cancellation will only cause cancel_test() to return true, so that the lane can cleanup manually (the actual value is irrelevant). + If wake_bool is true, the lane is also signalled so that execution returns from any pending linda operation. +
+ If timeout_secs is positive (aka "hard cancel"), waits for the request to be processed, or a timeout to occur. Linda operations detecting the cancellation request will raise a special cancellation error (meaning they won't return in that case). If force_kill_bool is true, forcekill_timeout can be set to tell how long lanes will wait for the OS thread to terminate before raising an error. Windows threads always terminate immediately, but it might not always be the case with some pthread implementations. Returns true if soft cancelling, or the lane was already done (in "done", "error" or "cancelled" status), or the cancellation was fruitful within timeout_secs timeout period.

@@ -1010,11 +1015,11 @@ 
 	h = lanes.linda( [opt_name])
 
-	bool = h:send( [timeout_secs,] key, ...)
+	bool|cancel_error = h:send( [timeout_secs,] key, ...)
 
-	[key, val] = h:receive( [timeout_secs,] key [, ...])
+	[key, val]|[cancel_error] = h:receive( [timeout_secs,] key [, ...])
 
-	[key, val [, ...]] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max])
+	[key, val [, ...]]|[cancel_error] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max])
 
 	[true] = h:limit( key, n_uint)
@@ -1041,12 +1046,16 @@

send() returns true if the sending succeeded, and false if the queue limit was met, and the queue did not empty enough during the given timeout. +
+ (Since version 3.7.8) send() returns lanes.cancel_error if interrupted by a soft cancel request.

Equally, receive() returns a key and the value extracted from it, or nothing for timeout. Note that nils can be sent and received; the key value will tell it apart from a timeout. -
+
Version 3.4.0 introduces an API change in the returned values: receive() returns the key followed by the value(s), in that order, and not the other way around. +
+ (Since version 3.7.8) receive() returns lanes.cancel_error if interrupted by a soft cancel request.

-- cgit v1.2.3-55-g6feb