1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
|
--
-- LANES.LUA
--
-- Multithreading and -core support for Lua
--
-- Authors: Asko Kauppi <akauppi@gmail.com>
-- Benoit Germain <bnt.germain@gmail.com>
--
-- History: see CHANGES
--
--[[
===============================================================================
Copyright (C) 2007-10 Asko Kauppi <akauppi@gmail.com>
Copyright (C) 2010-24 Benoit Germain <bnt.germain@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
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.
===============================================================================
]]--
local core = require "lanes_core"
-- Lua 5.1: module() creates a global variable
-- Lua 5.2: module() is gone
-- almost everything module() does is done by require() anyway
-- -> simply create a table, populate it, return it, and be done
local lanes = {}
-- #################################################################################################
-- Cache globals for code that might run under sandboxing
-- Making copies of necessary system libs will pass them on as upvalues;
-- only the first state doing "require 'lanes'" will need to have 'string'
-- and 'table' visible.
--
local assert = assert(assert)
local error = assert(error)
local pairs = assert(pairs)
local string = assert(string, "'string' library not available")
local string_find = assert(string.find)
local string_gmatch = assert(string.gmatch)
local string_format = assert(string.format)
local select = assert(select)
local setmetatable = assert(setmetatable)
local table = assert(table, "'table' library not available")
local table_insert = assert(table.insert)
local tonumber = assert(tonumber)
local tostring = assert(tostring)
local type = assert(type)
-- #################################################################################################
-- for error reporting when debugging stuff
--[[
local io = assert(io, "'io' library not available")
local function WR(str)
io.stderr:write(str.."\n" )
end
-- #################################################################################################
local function DUMP(tbl)
if not tbl then return end
local str=""
for k,v in pairs(tbl) do
str= str..k.."="..tostring(v).."\n"
end
WR(str)
end
]]
-- #################################################################################################
local isLuaJIT = (package and package.loaded.jit and jit.version) and true or false
local default_params =
{
-- LuaJIT provides a thread-unsafe allocator by default, so we need to protect it when used in parallel lanes
allocator = isLuaJIT and "protected" or nil,
-- it looks also like LuaJIT allocator may not appreciate direct use of its allocator for other purposes than the VM operation
internal_allocator = isLuaJIT and "libc" or "allocator",
keepers_gc_threshold = -1,
nb_user_keepers = 0,
on_state_create = nil,
shutdown_timeout = 0.25,
strip_functions = true,
track_lanes = false,
verbose_errors = false,
with_timers = false,
}
-- #################################################################################################
local boolean_param_checker = function(val_)
-- non-'boolean-false|nil' should be 'boolean-true'
if (not val_) or (val_ == true) then
return true
end
return nil, "not a boolean"
end
local param_checkers =
{
allocator = function(val_)
-- can be nil, "protected", or a function
if val_ ~= nil and val_ ~= "protected" and type(val_) ~= "function" then
return nil, "unknown value"
end
return true
end,
internal_allocator = function(val_)
-- can be "libc" or "allocator"
if type(val_) ~= "string" then
return nil, "not a string"
end
if val_ ~= "libc" and val_ ~= "allocator" then
return nil, "unknown value"
end
return true
end,
keepers_gc_threshold = function(val_)
-- keepers_gc_threshold should be a number
if type(val_) ~= "number" then
return nil, "not a number"
end
return true
end,
nb_user_keepers = function(val_)
-- nb_user_keepers should be a number in [0,100] (so that nobody tries to run OOM by specifying a huge amount)
if type(val_) ~= "number" then
return nil, "not a number"
end
if val_ < 0 or val_ > 100 then
return nil, "value out of range"
end
return true
end,
on_state_create = function(val_)
-- on_state_create may be nil or a function
if val_ ~= nil and type(val_) ~= "function" then
return nil, "not a function"
end
return true
end,
shutdown_timeout = function(val_)
-- shutdown_timeout should be a number in [0,3600]
if type(val_) ~= "number" then
return nil, "not a number"
end
if val_ < 0 or val_ > 3600 then
return nil, "value out of range"
end
return true
end,
strip_functions = boolean_param_checker,
track_lanes = boolean_param_checker,
verbose_errors = boolean_param_checker,
with_timers = boolean_param_checker,
}
-- #################################################################################################
local params_checker = function(user_settings_)
if not user_settings_ then
return default_params
end
-- make a copy of the table to leave the provided one unchanged, *and* to help ensure it won't change behind our back
local _compound_settings = {}
if type(user_settings_) ~= "table" then
error "Bad argument #1 to lanes.configure(), should be a table"
end
-- any setting unknown to Lanes raises an error
for _setting, _value in pairs(user_settings_) do
if not param_checkers[_setting] then
error("Unknown setting [" .. tostring(_setting) .. "] = " .. tostring(_value))
end
end
-- any setting not present in the provided parameters takes the default value
for _key, _checker in pairs(param_checkers) do
local my_param = user_settings_[_key]
local param
if my_param ~= nil then
param = my_param
else
param = default_params[_key]
end
local _result, _msg = _checker(param)
if not _result then
error("Bad parameter " .. _key .. ": " .. tostring(param) .. (_msg and " (" .. _msg .. ")" or ""), 2)
end
_compound_settings[_key] = param
end
return _compound_settings
end
-- #################################################################################################
local valid_libs =
{
["base"] = true,
["bit"] = true,
["bit32"] = true,
["coroutine"] = true,
["debug"] = true,
["ffi"] = true,
["io"] = true,
["jit"] = true,
["math"] = true,
["os"] = true,
["package"] = true,
["string"] = true,
["table"] = true,
["utf8"] = true,
--
["lanes_core"] = true
}
-- same structure, but contains only the libraries that the current Lua flavor actually supports
local supported_libs
-- #################################################################################################
local raise_option_error = function(name_, tv_, v_)
error("Bad '" .. name_ .. "' option: " .. tv_ .. " " .. string_format("%q", tostring(v_)), 4)
end
-- #################################################################################################
-- must match Lane::ErrorTraceLevel values
local error_trace_levels = {
minimal = 0,
basic = 1,
extended = 2
}
local opt_validators =
{
gc_cb = function(v_)
local tv = type(v_)
return (tv == "function") and v_ or raise_option_error("gc_cb", tv, v_)
end,
error_trace_level = function(v_)
local tv = type(v_)
return (error_trace_levels[v_] ~= nil) and v_ or raise_option_error("error_trace_level", tv, v_)
end,
globals = function(v_)
local tv = type(v_)
return (tv == "table") and v_ or raise_option_error("globals", tv, v_)
end,
name = function(v_)
local tv = type(v_)
return (tv == "string") and v_ or raise_option_error("name", tv, v_)
end,
package = function(v_)
local tv = type(v_)
return (tv == "table") and v_ or raise_option_error("package", tv, v_)
end,
priority = function(v_)
local tv = type(v_)
return (tv == "number") and v_ or raise_option_error("priority", tv, v_)
end,
required = function(v_)
local tv = type(v_)
return (tv == "table") and v_ or raise_option_error("required", tv, v_)
end
}
-- #############################################################################################
-- ##################################### lanes.gen() ###########################################
-- #############################################################################################
local process_gen_opt = function(...)
-- aggregrate all strings together, separated by "," as well as tables
-- the strings are a list of libraries to open
-- the tables contain the lane options
local opt = {}
local libs = nil
local n = select('#', ...)
-- we need at least a function
if n == 0 then
error("No arguments!", 2)
end
-- all arguments but the last must be nil, strings, or tables
for i = 1, n - 1 do
local v = select(i, ...)
local tv = type(v)
if tv == "string" then
libs = libs and libs .. "," .. v or v
elseif tv == "table" then
for k, vv in pairs(v) do
opt[k]= vv
end
elseif v == nil then
-- skip
else
error("Bad argument " .. i .. ": " .. tv .. " " .. string_format("%q", tostring(v)), 2)
end
end
-- the last argument should be a function or a string
local func = select(n, ...)
local functype = type(func)
if functype ~= "function" and functype ~= "string" then
error("Last argument not function or string: " .. functype .. " " .. string_format("%q", tostring(func)), 2)
end
-- check that the caller only provides reserved library names, and those only once
-- "*" is a special case that doesn't require individual checking
if libs and libs ~= "*" then
if string_find(libs, "*", 2, true) then
error "Libs specification '*' must be used alone"
end
local found = {}
-- accept lib identifiers (alphanumeric plus '.-_'), followed by an optional question mark
for s, question in string_gmatch(libs, "([%-%w_.]+)(%??)") do
if not valid_libs[s] then
error("Bad library name: " .. string_format("%q", tostring(s)), 2)
end
if question == '' and not supported_libs[s] then
error("Unsupported library: " .. string_format("%q", tostring(s)), 2)
end
found[s] = (found[s] or 0) + 1
if found[s] > 1 then
error("Libs specification contains " .. string_format("%q", tostring(s)) .. " more than once", 2)
end
end
end
-- validate that each option is known and properly valued
for k, v in pairs(opt) do
local validator = opt_validators[k]
if not validator then
error((type(k) == "number" and "Unkeyed option: " .. type(v) .. " " .. string_format("%q", tostring(v)) or "Bad '" .. tostring(k) .. "' option"), 2)
else
opt[k] = validator(v)
end
end
return func, libs, opt
end -- process_gen_opt
-- lane_h[1..n]: lane results, same as via 'lane_h:join()'
-- lane_h[0]: can be read to make sure a thread has finished (gives the number of available results)
-- lane_h[negative]: error message, without propagating the error
--
-- Reading a Lane result (or [0]) propagates a possible error in the lane
-- (and execution does not return). Cancelled lanes give 'nil' values.
--
-- lane_h.state: "pending"/"running"/"waiting"/"done"/"error"/"cancelled"
--
-- Note: Would be great to be able to have '__ipairs' metamethod, that gets
-- called by 'ipairs()' function to custom iterate objects. We'd use it
-- for making sure a lane has ended (results are available); not requiring
-- the user to precede a loop by explicit 'h[0]' or 'h:join()'.
--
-- Or, even better, 'ipairs()' should start valuing '__index' instead
-- of using raw reads that bypass it.
--
-----
-- lanes.gen([libs_str|opt_tbl [, ...],] lane_func ) ([...]) -> h
--
-- 'libs': nil: no libraries available (default)
-- "": only base library ('assert', 'print', 'unpack' etc.)
-- "math,os": math + os + base libraries (named ones + base)
-- "*": all standard libraries available
--
-- 'opt': .priority: int (-3..+3) smaller is lower priority (0 = default)
--
-- .globals: table of globals to set for a new thread (passed by value)
--
-- .required: table of packages to require
--
-- .gc_cb: function called when the lane handle is collected
--
-- ... (more options may be introduced later) ...
--
-- Calling with a function argument ('lane_func') ends the string/table
-- modifiers, and prepares a lane generator.
-- receives a sequence of strings and tables, plus a function
local gen = function(...)
local func, libs, opt = process_gen_opt(...)
local core_lane_new = assert(core.lane_new)
local priority, globals, package, required, gc_cb, name, error_trace_level = opt.priority, opt.globals, opt.package or package, opt.required, opt.gc_cb, opt.name, error_trace_levels[opt.error_trace_level]
return function(...)
-- must pass functions args last else they will be truncated to the first one
return core_lane_new(func, libs, priority, globals, package, required, gc_cb, name, error_trace_level, false, ...)
end
end -- gen()
local coro = function(...)
local func, libs, opt = process_gen_opt(...)
local core_lane_new = assert(core.lane_new)
local priority, globals, package, required, gc_cb, name, error_trace_level = opt.priority, opt.globals, opt.package or package, opt.required, opt.gc_cb, opt.name, error_trace_levels[opt.error_trace_level]
return function(...)
-- must pass functions args last else they will be truncated to the first one
return core_lane_new(func, libs, priority, globals, package, required, gc_cb, name, error_trace_level, true, ...)
end
end -- coro()
-- #################################################################################################
-- ####################################### Timers ##################################################
-- #################################################################################################
-- PUBLIC LANES API
local timer = function() error "timers are not active" end
local timers = timer
local timer_lane = nil
-- timerLinda should always exist, even when the settings disable the timers
-- is upvalue of timer stuff and lanes.sleep()
local timerLinda
local TGW_KEY = "(timer control)" -- the key does not matter, a 'weird' key may help debugging
local TGW_QUERY, TGW_REPLY = "(timer query)", "(timer reply)"
-- #################################################################################################
local configure_timers = function()
-- On first 'require "lanes"', a timer lane is spawned that will maintain
-- timer tables and sleep in between the timer events. All interaction with
-- the timer lane happens via a 'timerLinda' Linda, which is common to
-- all that 'require "lanes"'.
--
-- Linda protocol to timer lane:
--
-- TGW_KEY: linda_h, key, [wakeup_at_secs], [repeat_secs]
local now_secs = core.now_secs
local wakeup_conv = core.wakeup_conv
-- Timer lane; initialize only on the first 'require "lanes"' instance (which naturally has 'table' always declared)
local first_time_key = "first time"
timerLinda:restrict(first_time_key, "set/get")
local _, _first_time_val = timerLinda:get(first_time_key)
local first_time = (_first_time_val == nil)
timerLinda:set(first_time_key, true)
if first_time then
assert(type(now_secs) == "function")
-----
-- Snore loop (run as a lane on the background)
--
-- High priority, to get trustworthy timings.
--
-- We let the timer lane be a "free running" thread; no handle to it
-- remains.
--
local timer_body = function()
--
-- { [deep_linda_lightuserdata]= { [deep_linda_lightuserdata]=linda_h,
-- [key]= { wakeup_secs [,period_secs] } [, ...] },
-- }
--
-- Collection of all running timers, indexed with linda's & key.
--
-- Note that we need to use the deep lightuserdata identifiers, instead
-- of 'linda_h' themselves as table indices. Otherwise, we'd get multiple
-- entries for the same timer.
--
-- The 'hidden' reference to Linda proxy is used in 'check_timers()' but
-- also important to keep the Linda alive, even if all outside world threw
-- away pointers to it (which would ruin uniqueness of the deep pointer).
-- Now we're safe.
--
local collection = {}
local get_timers = function()
local r = {}
for deep, t in pairs(collection) do
-- WR(tostring(deep))
local l = t[deep]
for key, timer_data in pairs(t) do
if key ~= deep then
table_insert(r, {l, key, timer_data})
end
end
end
return r
end -- get_timers()
--
-- set_timer(linda_h, key [,wakeup_at_secs [,period_secs]] )
--
local set_timer = function(linda_, key_, wakeup_at_, period_)
assert(wakeup_at_ == nil or wakeup_at_ > 0.0)
assert(period_ == nil or period_ > 0.0)
local linda_deep = linda_:deep()
assert(linda_deep)
-- Find or make a lookup for this timer
--
local t1 = collection[linda_deep]
if not t1 then
t1 = { [linda_deep] = linda_} -- proxy to use the Linda
collection[linda_deep] = t1
end
if wakeup_at_ == nil then
-- Clear the timer
--
t1[key_]= nil
-- Remove empty tables from collection; speeds timer checks and
-- lets our 'safety reference' proxy be gc:ed as well.
--
local empty = true
for k, _ in pairs(t1) do
if k ~= linda_deep then
empty = false
break
end
end
if empty then
collection[linda_deep] = nil
end
-- Note: any unread timer value is left at 'linda_[key_]' intensionally;
-- clearing a timer just stops it.
else
-- New timer or changing the timings
--
local t2 = t1[key_]
if not t2 then
t2 = {}
t1[key_] = t2
end
t2[1] = wakeup_at_
t2[2] = period_ -- can be 'nil'
end
end -- set_timer()
-----
-- [next_wakeup_at]= check_timers()
-- Check timers, and wake up the ones expired (if any)
-- Returns the closest upcoming (remaining) wakeup time (or 'nil' if none).
local check_timers = function()
local now = now_secs()
local next_wakeup
for linda_deep, t1 in pairs(collection) do
for key, t2 in pairs(t1) do
--
if key == linda_deep then
-- no 'continue' in Lua :/
else
-- 't2': { wakeup_at_secs [,period_secs] }
--
local wakeup_at= t2[1]
local period= t2[2] -- may be 'nil'
if wakeup_at <= now then
local linda = t1[linda_deep]
assert(linda)
linda:set(key, now)
-- 'pairs()' allows the values to be modified (and even
-- removed) as far as keys are not touched
if not period then
-- one-time timer; gone
--
t1[key] = nil
wakeup_at = nil -- no 'continue' in Lua :/
else
-- repeating timer; find next wakeup (may jump multiple repeats)
--
repeat
wakeup_at= wakeup_at+period
until wakeup_at > now
t2[1]= wakeup_at
end
end
if wakeup_at and ((not next_wakeup) or (wakeup_at < next_wakeup)) then
next_wakeup = wakeup_at
end
end
end -- t2 loop
end -- t1 loop
return next_wakeup -- may be 'nil'
end -- check_timers()
local timer_gateway_batched = timerLinda.batched
set_finalizer(function(err, stk)
if err and type(err) ~= "userdata" then
error("LanesTimer error: "..tostring(err))
--elseif type(err) == "userdata" then
-- WR("LanesTimer after cancel" )
--else
-- WR("LanesTimer finalized")
end
end)
while true do
local next_wakeup = check_timers()
-- Sleep until next timer to wake up, or a set/clear command
--
local secs
if next_wakeup then
secs = next_wakeup - now_secs()
if secs < 0 then secs = 0 end
end
-- poll both TGW_KEY and TGW_QUERY at the same time
local _timerKey, _what = timerLinda:receive(secs, TGW_KEY, TGW_QUERY)
if _timerKey == TGW_KEY then
assert(getmetatable(_what) == "Linda") -- '_what' should be a linda on which the client sets a timer
local _, key, wakeup_at, period = timerLinda:receive(0, timer_gateway_batched, TGW_KEY, 3)
assert(key)
set_timer(_what, key, wakeup_at, period and period > 0 and period or nil)
elseif _timerKey == TGW_QUERY then
if _what == "get_timers" then
timerLinda:send(TGW_REPLY, get_timers())
else
timerLinda:send(TGW_REPLY, "unknown query " .. _what)
end
else -- got no value while block-waiting
assert(_what == cancel_error or _what == "timeout")
-- WR("timer lane: no linda, aborted?")
end
end
end -- timer_body()
timer_lane = gen("lanes_core,table", { name = "LanesTimer", package = {}, priority = core.max_prio }, timer_body)()
end -- first_time
-----
-- = timer(linda_h, key_val, date_tbl|first_secs [,period_secs] )
--
-- PUBLIC LANES API
timer = function(linda_, key_, when_, period_)
if getmetatable(linda_) ~= "Linda" then
error "expecting a Linda"
end
if when_ == 0.0 then
-- Caller expects to get current time stamp in Linda, on return
-- (like the timer had expired instantly); it would be good to set this
-- as late as possible (to give most current time) but also we want it
-- to precede any possible timers that might start striking.
--
linda_:set(key_, now_secs())
if not period_ or period_ == 0.0 then
timerLinda:send(TGW_KEY, linda_, key_, nil, nil ) -- clear the timer
return -- nothing more to do
end
when_ = period_
end
local wakeup_at = type(when_)=="table" and wakeup_conv(when_) -- given point of time
or (when_ and now_secs()+when_ or nil)
-- queue to timer
--
timerLinda:send(TGW_KEY, linda_, key_, wakeup_at, period_)
end -- timer()
-----
-- {[{linda, slot, when, period}[,...]]} = timers()
--
-- PUBLIC LANES API
timers = function()
timerLinda:send(TGW_QUERY, "get_timers")
-- can be nil, <something> in case of cancellation or timeout
local _k, _t = timerLinda:receive(TGW_REPLY)
-- success: return the table
if _k then
return _t
end
-- error: return everything we got
return _k, _t
end -- timers()
end -- configure_timers()
-- #################################################################################################
-- ##################################### lanes.genlock() ###########################################
-- #################################################################################################
-- These functions are just surface sugar, but make solutions easier to read.
-- Not many applications should even need explicit locks or atomic counters.
--
-- [true [, ...]= trues(uint)
--
local function trues(n)
if n > 0 then
return true, trues(n - 1)
end
end
-- avoid pulling the whole core module as upvalue when cancel_error is enough
local cancel_error
-- #################################################################################################
-- lock_f = lanes.genlock(linda_h, key [,N_uint=1] )
--
-- = lock_f(+M) -- acquire M
-- ...locked...
-- = lock_f(-M) -- release M
--
-- Returns an access function that allows 'N' simultaneous entries between
-- acquire (+M) and release (-M). For binary locks, use M==1.
--
local genlock = function(linda_, key_, N)
-- clear existing data and set the limit
N = N or 1
local _status, _err = linda_:set(key_)
if _err == cancel_error then
return cancel_error
end
local _status, _err = linda_:limit(key_, N)
if _err == cancel_error then
return cancel_error
end
-- use an optimized version for case N == 1
return (N == 1) and
function(M_, mode_)
local timeout = (mode_ == "try") and 0 or nil
if M_ > 0 then
-- 'nil' timeout allows 'key_' to be numeric
local _status, _err = linda_:send(timeout, key_, true) -- suspends until been able to push them
-- if success, _status is true, that's what we return
-- if failure, _status is nil, _err contains the error, that's what we return
-- propagate cancel_error if we got it, else return true or false
return (_err == cancel_error and _err) or (_status and true or false)
else
local _k, _v = linda_:receive(nil, key_)
-- propagate cancel_error if we got it, else return true or false
return (_v == cancel_error and _v) or (_k and true or false)
end
end
or
function(M_, mode_)
local timeout = (mode_ == "try") and 0 or nil
if M_ > 0 then
-- 'nil' timeout allows 'key_' to be numeric
return linda_:send(timeout, key_, trues(M_)) -- suspends until been able to push them
else
local _k, _v = linda_:receive(nil, linda_.batched, key_, -M_)
-- propagate cancel_error if we got it, else return true or false
return (_v == cancel_error and _v) or (_k and true or false)
end
end
end -- genlock
-- #################################################################################################
-- #################################### lanes.genatomic() ##########################################
-- #################################################################################################
-- atomic_f = lanes.genatomic(linda_h, key [,initial_num=0.0])
--
-- int|cancel_error = atomic_f([diff_num = 1.0])
--
-- Returns an access function that allows atomic increment/decrement of the
-- number in 'key'.
--
local genatomic = function(linda_, key_, initial_val_)
-- clears existing data (also queue). the slot may contain the stored value, and an additional boolean value
local _status, _err = linda_:limit(key_, 2)
if _err == cancel_error then
return cancel_error
end
local _status, _err = linda_:set(key_, initial_val_ or 0.0)
if _err == cancel_error then
return cancel_error
end
return function(diff_)
-- 'nil' allows 'key_' to be numeric
-- suspends until our 'true' is in
local _res, _err = linda_:send(nil, key_, true)
if _err == cancel_error then
return cancel_error
end
local _, val = linda_:get(key_)
if val ~= cancel_error then
val = val + (diff_ or 1.0)
-- set() releases the lock by emptying queue
local _res, _err = linda_:set(key_, val)
if _err == cancel_error then
val = cancel_error
end
end
return val
end
end -- genatomic
-- #################################################################################################
-- ################################## lanes.configure() ############################################
-- #################################################################################################
-- start with a protected metatable
local lanesMeta = { __metatable = "Lanes" }
-- this function is available in the public interface until it is called, after which it disappears
local configure = function(settings_)
-- Configure called so remove metatable from lanes
lanesMeta.__metatable = nil -- unprotect the metatable
setmetatable(lanes, nil) -- remove it
lanes.configure = function() return lanes end -- no need to configure anything again
-- now we can configure Lanes core
local settings = core.configure and core.configure(params_checker(settings_)) or core.settings
--
lanes.ABOUT =
{
author= "Asko Kauppi <akauppi@gmail.com>, Benoit Germain <bnt.germain@gmail.com>",
description= "Running multiple Lua states in parallel",
license= "MIT/X11",
copyright= "Copyright (c) 2007-10, Asko Kauppi; (c) 2011-23, Benoit Germain",
version = assert(core.version)
}
-- avoid pulling the whole core module as upvalue when cancel_error is enough
-- these are locals declared above, that we need to set prior to calling configure_timers()
cancel_error = assert(core.cancel_error)
supported_libs = assert(core.supported_libs())
timerLinda = assert(core.timerLinda)
if settings.with_timers then
configure_timers(settings)
end
-- activate full interface
lanes.cancel_error = core.cancel_error
lanes.collectgarbage = core.collectgarbage
lanes.finally = core.finally
lanes.linda = core.linda
lanes.nameof = core.nameof
lanes.now_secs = core.now_secs
lanes.null = core.null
lanes.register = core.register
lanes.require = core.require
lanes.set_singlethreaded = core.set_singlethreaded
lanes.set_thread_affinity = core.set_thread_affinity
lanes.set_thread_priority = core.set_thread_priority
lanes.sleep = core.sleep
lanes.threads = core.threads or function() error "lane tracking is not available" end -- core.threads isn't registered if settings.track_lanes is false
lanes.gen = gen
lanes.coro = coro
lanes.genatomic = genatomic
lanes.genlock = genlock
lanes.timer = timer
lanes.timer_lane = timer_lane
lanes.timers = timers
return lanes
end -- lanes.configure
-- #################################################################################################
lanesMeta.__index = function(lanes_, k_)
-- This is called when some functionality is accessed without calling configure()
configure() -- initialize with default settings
-- Access the required key
return lanes_[k_]
end
lanes.configure = configure
setmetatable(lanes, lanesMeta)
-- #################################################################################################
-- no need to force calling configure() manually excepted the first time (other times will reuse the internally stored settings of the first call)
if core.settings then
return configure()
else
return lanes
end
--the end
|