diff options
author | Benoit Germain <benoit.germain@ubisoft.com> | 2024-06-10 16:49:58 +0200 |
---|---|---|
committer | Benoit Germain <benoit.germain@ubisoft.com> | 2024-06-10 16:49:58 +0200 |
commit | ae582acdb1bfb3fb4171682b884545d174e95aa9 (patch) | |
tree | b0c9c0b14f6d57cd8ce1c14d4d23df1adb0bc539 /docs | |
parent | 3f5c16116a3a7740ac4ac62b663661d772543c2e (diff) | |
download | lanes-ae582acdb1bfb3fb4171682b884545d174e95aa9.tar.gz lanes-ae582acdb1bfb3fb4171682b884545d174e95aa9.tar.bz2 lanes-ae582acdb1bfb3fb4171682b884545d174e95aa9.zip |
linda:send() returns nil,<something> in case of error
Diffstat (limited to 'docs')
-rw-r--r-- | docs/index.html | 41 |
1 files changed, 24 insertions, 17 deletions
diff --git a/docs/index.html b/docs/index.html index 24c7c52..5675f65 100644 --- a/docs/index.html +++ b/docs/index.html | |||
@@ -1221,7 +1221,7 @@ | |||
1221 | </p> | 1221 | </p> |
1222 | 1222 | ||
1223 | <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> | 1223 | <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> |
1224 | true|lanes.cancel_error = h:limit(key, n_uint) | 1224 | true|(nil,[lanes.cancel_error|"timeout"]) = h:limit(key, n_uint) |
1225 | </pre></td></tr></table> | 1225 | </pre></td></tr></table> |
1226 | 1226 | ||
1227 | <p> | 1227 | <p> |
@@ -1238,42 +1238,49 @@ | |||
1238 | Timeouts are given in seconds (>= 0, millisecond accuracy) or <tt>nil</tt>. Timeout can be omitted only if the first key is not a number (then it is equivalent to an infinite duration).<br/> | 1238 | Timeouts are given in seconds (>= 0, millisecond accuracy) or <tt>nil</tt>. Timeout can be omitted only if the first key is not a number (then it is equivalent to an infinite duration).<br/> |
1239 | Each key acts as a FIFO queue. There is no limit to the number of keys a Linda may contain. Different Lindas can have identical keys, which are totally unrelated. | 1239 | Each key acts as a FIFO queue. There is no limit to the number of keys a Linda may contain. Different Lindas can have identical keys, which are totally unrelated. |
1240 | </p> | 1240 | </p> |
1241 | |||
1242 | <p> | ||
1243 | Multiple values can be sent to a given key at once, atomically (the send will fail unless all the values fit within the queue limit). This can be useful for multiple producer scenarios, if the protocols used are giving data in streams of multiple units. | ||
1244 | Atomicity avoids the producers from garbling each others messages, which could happen if the units were sent individually. | ||
1245 | </p> | ||
1246 | |||
1241 | <p> | 1247 | <p> |
1242 | If no data is provided after the key, <tt>send()</tt> raises an error.<br/> | 1248 | If no data is provided after the key, <tt>send()</tt> raises an error.<br/> |
1243 | Also, if <tt>linda.null</tt> or <tt>lanes.null</tt> is sent as data in a Linda, it will be read as a <tt>nil</tt>.<br/> | 1249 | Also, if <tt>linda.null</tt> or <tt>lanes.null</tt> is sent as data in a Linda, it will be read as a <tt>nil</tt>.<br/> |
1244 | <tt>send()</tt> returns <tt>true</tt> if the sending succeeded, and <tt>false</tt> if the queue limit was met, and the queue did not empty enough during the given timeout.<br/> | 1250 | <tt>send()</tt> return values can be: |
1245 | <tt>send()</tt> returns <tt>lanes.cancel_error</tt> if interrupted by a soft cancel request.<br/> | 1251 | <ul> |
1252 | <li><tt>true</tt> on success.</li> | ||
1253 | <li><tt>nil, "timeout"</tt> if the queue limit was met, and the queue did not empty enough during the given duration.</li> | ||
1254 | <li><tt>nil, lanes.cancel_error</tt> if interrupted by a soft cancel request.</li> | ||
1255 | <li>Raises <tt>lanes.cancel_error</tt> if interrupted by a hard cancel request.</li> | ||
1256 | </ul> | ||
1246 | </p> | 1257 | </p> |
1247 | 1258 | ||
1248 | <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> | 1259 | <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> |
1249 | key, val = h:receive([timeout_secs,] key [, key...]) | 1260 | key, val = h:receive([timeout_secs,] key [, key...]) |
1250 | 1261 | ||
1251 | key, val [, val...] = h:receive(timeout, h.batched, key, n_uint_min[, n_uint_max]) | 1262 | key, val [, val...] = h:receive([timeout,] h.batched, key, n_uint_min[, n_uint_max]) |
1252 | </pre></td></tr></table> | 1263 | </pre></td></tr></table> |
1253 | 1264 | ||
1254 | |||
1255 | <p> | ||
1256 | The <tt>send()</tt> and <tt>receive()</tt> methods use Linda keys as FIFO stacks (first in, first out).<br/> | ||
1257 | In batched mode, <tt>linda:receive()</tt> will raise an error if <tt>min_count < 1</tt> or <tt>max_count < min_count</tt>. | ||
1258 | </p> | ||
1259 | |||
1260 | <p> | 1265 | <p> |
1261 | Note that any number of lanes can be reading or writing a Linda. There can be many producers, and many consumers. It is up to you. | 1266 | Unbatched <tt>receive()</tt> return values can be: |
1267 | <ul> | ||
1268 | <li><tt>nil, lanes.cancel_error</tt> if interrupted by a hard cancel request.</li> | ||
1269 | <li><tt>nil, "timeout"</tt> if nothing was available.</li> | ||
1270 | <li>A key and the value extracted from it. Note that <tt>nil</tt> can be sent and received; the <tt>key</tt> value will tell it apart from a timeout.</li> | ||
1271 | </ul> | ||
1262 | </p> | 1272 | </p> |
1263 | 1273 | ||
1264 | <p> | 1274 | <p> |
1265 | <a href="#cancelling">Hard cancellation</a> will cause pending Linda operations to abort execution of the lane through a cancellation error. This means that you have to install a <a href="#finalizers">finalizer</a> in your lane if you want to run some code in that situation. | 1275 | In batched mode, <tt>linda:receive()</tt> will raise an error if <tt>min_count < 1</tt> or <tt>max_count < min_count</tt>. |
1266 | </p> | 1276 | </p> |
1267 | 1277 | ||
1268 | <p> | 1278 | <p> |
1269 | Equally, <tt>receive()</tt> returns a key and the value extracted from it. Note that <tt>nil</tt>s can be sent and received; the <tt>key</tt> value will tell it apart from a timeout.<br/> | 1279 | Note that any number of lanes can be reading or writing a Linda. There can be many producers, and many consumers. It is up to you. |
1270 | <tt>receive()</tt> returns <tt>nil, lanes.cancel_error</tt> if interrupted by a hard cancel request.<br/> | ||
1271 | <tt>receive()</tt> returns <tt>nil, "timeout"</tt> if nothing was available. | ||
1272 | </p> | 1280 | </p> |
1273 | 1281 | ||
1274 | <p> | 1282 | <p> |
1275 | Multiple values can be sent to a given key at once, atomically (the send will fail unless all the values fit within the queue limit). This can be useful for multiple producer scenarios, if the protocols used are giving data in streams of multiple units. | 1283 | Remember that <a href="#cancelling">Hard cancellation</a> will cause pending Linda operations to abort execution of the lane through a cancellation error. This means that you have to install a <a href="#finalizers">finalizer</a> in your lane if you want to run some code in that situation. |
1276 | Atomicity avoids the producers from garbling each others messages, which could happen if the units were sent individually. | ||
1277 | </p> | 1284 | </p> |
1278 | 1285 | ||
1279 | <p> | 1286 | <p> |