xs/future.xs

filter: Statementstmt 93.5% 72 / 77 Branchbran 70.9% 61 / 86 Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 81.6% 133 / 163 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« xs/csp.xs ↑ Summary include/punk/punk_import.h »
1 MODULE = Punk PACKAGE = Punk::Future
2  
3 PROTOTYPES: DISABLE
4  
5 # Punk::Future, in C (punk_future.h). A Future.pm-compatible async result that
6 # runs on the Hyperman loop when live and blocks otherwise. lib/Punk/Future.pm
7 # is documentation. (Core stage: create / settle / state / callbacks / get.)
8  
9 SV *
10 new(class)
11 SV *class
12 CODE:
13 111 RETVAL = pf_bless(aTHX_ pf_new(aTHX), pf_class_of(aTHX_ class));
14 OUTPUT:
15 RETVAL
16  
17 # done(@values) / fail(@failure): settle a pending future. Chains.
18 SV *
19 done(self, ...)
20 SV *self
21 ALIAS:
22 fail = 1
23 AWAIT_DONE = 2
24 AWAIT_FAIL = 3
25 CODE:
26 {
27 47 punk_future *pf = pf_of(aTHX_ self);
28 47 AV *vals = newAV();
29 int i;
30 90 ▶ for (i = 1; i < items; i++) av_push(vals, newSVsv(ST(i)));
Branch: 1 branch
BranchTrueFalseTotal
for (i = 1; i < items; i++) av_push(vals, newSVsv(ST(i))); 43 47 90
31 /* the low bit of ix is the outcome, so the AWAIT_ spellings pair off
32 * with the ones they alias */
33 47 ▶ pf_settle(aTHX_ pf, self, (ix & 1) ? PF_FAILED : PF_DONE, vals);
Branch: 1 branch
BranchTrueFalseTotal
pf_settle(aTHX_ pf, self, (ix & 1) ? PF_FAILED : PF_DONE, vals); 11 36 47
34 47 RETVAL = newSVsv(self);
35 }
36 OUTPUT:
37 RETVAL
38  
39 IV
40 is_ready(self)
41 SV *self
42 ALIAS:
43 is_done = 1
44 is_failed = 2
45 is_cancelled = 3
46 AWAIT_IS_READY = 4
47 AWAIT_IS_CANCELLED = 5
48 CODE:
49 {
50 97 int st = pf_of(aTHX_ self)->state;
51 /* a switch, not a ternary chain: the chain's last arm was a
52 * fallthrough that would quietly answer for any ix added later */
53 96 switch (ix) {
54 11 case 1: RETVAL = (st == PF_DONE); break;
55 25 case 2: RETVAL = (st == PF_FAILED); break;
56 19 case 3: case 5: RETVAL = (st == PF_CANCELLED); break;
57 41 default: RETVAL = (st != PF_PENDING); break; /* 0, 4 */
58 }
59 }
60 OUTPUT:
61 RETVAL
62  
63 IV
64 state(self)
65 SV *self
66 CODE:
67 1 ▶ RETVAL = pf_of(aTHX_ self)->state;
Branch: 1 branch
BranchTrueFalseTotal
RETVAL = pf_of(aTHX_ self)->state; 0 1 1
68 OUTPUT:
69 RETVAL
70  
71 # on_ready($cb) fires $cb->($future) on settle; on_done/on_fail fire
72 # $cb->(@values) for the matching outcome. Fire at once if already settled.
73 SV *
74 on_ready(self, thing)
75 SV *self
76 SV *thing
77 ALIAS:
78 on_done = 1
79 on_fail = 2
80 on_cancel = 3
81 AWAIT_ON_READY = 4
82 CODE:
83 {
84 /* ix stops being the reaction kind here. It was PFR_* by coincidence
85 * of declaration order, which is not something an alias list should
86 * have to know: an alias landing on the wrong number would register a
87 * reaction that never fires, and a never-fired reaction is a hang with
88 * nothing to report. */
89 static const int kind[] = {
90 PFR_ON_READY, /* 0 on_ready */
91 PFR_ON_DONE, /* 1 on_done */
92 PFR_ON_FAIL, /* 2 on_fail */
93 PFR_ON_CANCEL, /* 3 on_cancel */
94 PFR_ON_READY /* 4 AWAIT_ON_READY */
95 };
96 55 pf_react(aTHX_ pf_of(aTHX_ self), self, kind[ix], thing);
97 55 RETVAL = newSVsv(self);
98 }
99 OUTPUT:
100 RETVAL
101  
102 # The protocol's two cancel registrations. They are a separate body from
103 # on_cancel rather than two more aliases because they must return NOTHING:
104 # these are called by Future::AsyncAwait on the future it is about to hand
105 # back, and replacing the invocant on the argument stack with a fresh copy of
106 # it - which is what returning `$self` does here - corrupts that future.
107 # The protocol defines no return value for either, so there is none.
108 void
109 AWAIT_ON_CANCEL(self, thing)
110 SV *self
111 SV *thing
112 ALIAS:
113 AWAIT_CHAIN_CANCEL = 1
114 CODE:
115 PERL_UNUSED_VAR(ix);
116 12 pf_react(aTHX_ pf_of(aTHX_ self), self, PFR_ON_CANCEL, thing);
117  
118 # get / result: block until ready, then return the values (or die the failure).
119 # AWAIT_WAIT is the same thing - it is what a toplevel await resolves to.
120 # AWAIT_GET is defined only on a future that is already ready, so it reads
121 # where the others wait; the two croaks stay distinguishable on purpose.
122 void
123 get(self)
124 SV *self
125 ALIAS:
126 result = 1
127 AWAIT_WAIT = 2
128 AWAIT_GET = 3
129 PPCODE:
130 {
131 241 punk_future *pf = pf_of(aTHX_ self);
132 SSize_t i, n;
133 241 ▶ if (ix == 3) {
Branch: 1 branch
BranchTrueFalseTotal
if (ix == 3) { 25 216 241
134 25 ▶ if (pf->state == PF_PENDING)
Branch: 1 branch
BranchTrueFalseTotal
if (pf->state == PF_PENDING) 1 24 25
135 1 croak("Punk::Future: AWAIT_GET on a future that is not ready");
136 }
137 216 ▶ else if (pf->state == PF_PENDING) pf_await(aTHX_ self); /* pump/sleep */
Branch: 1 branch
BranchTrueFalseTotal
else if (pf->state == PF_PENDING) pf_await(aTHX_ self); /* pump/sleep */ 173 43 216
138 /* pf_await ran the loop, and anything on it may have grown the value
139 * stack; a grown stack is reallocated, so the SP captured on entry
140 * points into freed memory. Re-derive it before pushing. */
141 237 SP = PL_stack_base + ax - 1;
142 237 ▶ if (pf->state == PF_CANCELLED)
Branch: 1 branch
BranchTrueFalseTotal
if (pf->state == PF_CANCELLED) 0 237 237
143 0 croak("Punk::Future: get on a cancelled future");
144 237 ▶ if (pf->state == PF_FAILED) {
Branch: 1 branch
BranchTrueFalseTotal
if (pf->state == PF_FAILED) { 12 225 237
145 12 ▶ SV **f = pf->vals ? av_fetch(pf->vals, 0, 0) : NULL;
Branch: 1 branch
BranchTrueFalseTotal
SV **f = pf->vals ? av_fetch(pf->vals, 0, 0) : NULL; 12 0 12
146 12 ▶ croak_sv(f && *f ? *f : sv_2mortal(newSVpvs("Punk::Future failed")));
Branch: 2 branches
BranchTrueFalseTotal
croak_sv(f && *f ? *f : sv_2mortal(newSVpvs("Punk::Future failed"))); 12 0 12
croak_sv(f && *f ? *f : sv_2mortal(newSVpvs("Punk::Future failed"))); 12 0 12
147 }
148 225 ▶ n = pf->vals ? av_len(pf->vals) + 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
n = pf->vals ? av_len(pf->vals) + 1 : 0; 225 0 225
149 /* Scalar context hands back the FIRST value, as Future.pm does. An
150 * XSUB otherwise returns whatever was pushed last, which made a
151 * multi-value future yield its tail - and punk_coerce and
152 * _finish_future both call this in scalar context. */
153 225 ▶ if (GIMME_V != G_ARRAY) {
Branch: 1 branch
BranchTrueFalseTotal
if (GIMME_V != G_ARRAY) { 66 159 225
154 66 ▶ SV **f = n ? av_fetch(pf->vals, 0, 0) : NULL;
Branch: 1 branch
BranchTrueFalseTotal
SV **f = n ? av_fetch(pf->vals, 0, 0) : NULL; 63 3 66
155 66 ▶ XPUSHs(f && *f ? sv_2mortal(newSVsv(*f)) : &PL_sv_undef);
Branch: 3 branches
BranchTrueFalseTotal
XPUSHs(f && *f ? sv_2mortal(newSVsv(*f)) : &PL_sv_undef); 0 66 66
XPUSHs(f && *f ? sv_2mortal(newSVsv(*f)) : &PL_sv_undef); 63 3 66
XPUSHs(f && *f ? sv_2mortal(newSVsv(*f)) : &PL_sv_undef); 63 0 63
156 }
157 else {
158 159 ▶ EXTEND(SP, n);
Branch: 2 branches
BranchTrueFalseTotal
EXTEND(SP, n); 159 0 159
EXTEND(SP, n); 0 159 159
159 325 ▶ for (i = 0; i < n; i++)
Branch: 1 branch
BranchTrueFalseTotal
for (i = 0; i < n; i++) 166 159 325
160 166 PUSHs(sv_2mortal(newSVsv(*av_fetch(pf->vals, i, 0))));
161 }
162 }
163  
164 # the first failure value of a failed future, else undef
165 SV *
166 failure(self)
167 SV *self
168 CODE:
169 {
170 56 punk_future *pf = pf_of(aTHX_ self);
171 3 ▶ SV **f = (pf->state == PF_FAILED && pf->vals)
Branch: 1 branch
BranchTrueFalseTotal
SV **f = (pf->state == PF_FAILED && pf->vals) 3 0 3
172 59 ▶ ? av_fetch(pf->vals, 0, 0) : NULL;
Branch: 1 branch
BranchTrueFalseTotal
? av_fetch(pf->vals, 0, 0) : NULL; 3 53 56
173 56 ▶ RETVAL = (f && *f) ? newSVsv(*f) : newSV(0);
Branch: 2 branches
BranchTrueFalseTotal
RETVAL = (f && *f) ? newSVsv(*f) : newSV(0); 3 53 56
RETVAL = (f && *f) ? newSVsv(*f) : newSV(0); 3 0 3
174 }
175 OUTPUT:
176 RETVAL
177  
178 # then($on_done, $on_fail?): a new future the callback's result settles.
179 # The else/catch($on_fail) pair takes the failure branch only, and
180 # followed_by($cb) calls $cb->($self) on any outcome. A callback that
181 # returns a future is adopted.
182 #
183 # Keep 'else' off the start of a comment line here: xsubpp matches
184 # /^#[ \t]*(if|ifn?def|elif|else|endif)\b/ before it decides a '#' line is a
185 # comment, so '# else/catch(...)' parsed as a bare #else and failed the build
186 # with "'else' with no matching 'if'".
187 SV *
188 then(self, on_done, on_fail = &PL_sv_undef)
189 SV *self
190 SV *on_done
191 SV *on_fail
192 CODE:
193 34 RETVAL = pf_make_chain(aTHX_ self, on_done, on_fail, 0);
194 OUTPUT:
195 RETVAL
196  
197 # named _pf_else because an XSUB literally named `else` makes xsubpp emit a
198 # bare C `else`; the public names are the aliases.
199 SV *
200 _pf_else(self, on_fail)
201 SV *self
202 SV *on_fail
203 ALIAS:
204 else = 1
205 catch = 2
206 CODE:
207 PERL_UNUSED_VAR(ix);
208 2 RETVAL = pf_make_chain(aTHX_ self, &PL_sv_undef, on_fail, 0);
209 OUTPUT:
210 RETVAL
211  
212 SV *
213 followed_by(self, cb)
214 SV *self
215 SV *cb
216 CODE:
217 1 RETVAL = pf_make_chain(aTHX_ self, cb, &PL_sv_undef, 1);
218 OUTPUT:
219 RETVAL
220  
221 # A new pending future of the same class, carrying the source's loop. This is
222 # how an async sub gets the future it returns - see pf_clone for why the loop
223 # travels with it.
224 SV *
225 AWAIT_CLONE(self)
226 SV *self
227 CODE:
228 11 RETVAL = pf_clone(aTHX_ self);
229 OUTPUT:
230 RETVAL
231  
232 # done_future(@v) / fail_future(@v): an already-settled future.
233 SV *
234 done_future(class, ...)
235 SV *class
236 ALIAS:
237 fail_future = 1
238 AWAIT_NEW_DONE = 2
239 AWAIT_NEW_FAIL = 3
240 CODE:
241 {
242 28 punk_future *pf = pf_new(aTHX);
243 28 AV *vals = newAV();
244 int i;
245 28 RETVAL = pf_bless(aTHX_ pf, pf_class_of(aTHX_ class));
246 56 ▶ for (i = 1; i < items; i++) av_push(vals, newSVsv(ST(i)));
Branch: 1 branch
BranchTrueFalseTotal
for (i = 1; i < items; i++) av_push(vals, newSVsv(ST(i))); 28 28 56
247 /* The protocol never calls AWAIT_NEW_FAIL with no message, but a
248 * failure with no failure value is not a failure. Only the AWAIT_
249 * spelling gets the default; fail_future's own behaviour is left
250 * exactly as it was. */
251 28 ▶ if (ix == 3 && items < 2) av_push(vals, newSVpvs("Failed\n"));
Branch: 2 branches
BranchTrueFalseTotal
if (ix == 3 && items < 2) av_push(vals, newSVpvs("Failed\n")); 3 25 28
if (ix == 3 && items < 2) av_push(vals, newSVpvs("Failed\n")); 1 2 3
252 28 ▶ pf_settle(aTHX_ pf, RETVAL, (ix & 1) ? PF_FAILED : PF_DONE, vals);
Branch: 1 branch
BranchTrueFalseTotal
pf_settle(aTHX_ pf, RETVAL, (ix & 1) ? PF_FAILED : PF_DONE, vals); 6 22 28
253 }
254 OUTPUT:
255 RETVAL
256  
257 # needs_all/needs_any/wait_all/wait_any(@futures), and all/any aliases.
258 SV *
259 needs_all(class, ...)
260 SV *class
261 ALIAS:
262 needs_any = 1
263 wait_all = 2
264 wait_any = 3
265 all = 4
266 any = 5
267 CODE:
268 {
269 9 int mode = (ix == 4) ? PFC_NEEDS_ALL
270 9 ▶ : (ix == 5) ? PFC_NEEDS_ANY : (int)ix;
Branch: 2 branches
BranchTrueFalseTotal
: (ix == 5) ? PFC_NEEDS_ANY : (int)ix; 7 2 9
: (ix == 5) ? PFC_NEEDS_ANY : (int)ix; 5 2 7
271 9 int n = items - 1, i;
272 SV **inputs, *G;
273 9 G = pf_bless(aTHX_ pf_new(aTHX), pf_class_of(aTHX_ class));
274 9 ▶ Newx(inputs, n > 0 ? n : 1, SV *);
Branch: 1 branch
BranchTrueFalseTotal
Newx(inputs, n > 0 ? n : 1, SV *); 7 2 9
275 24 ▶ for (i = 0; i < n; i++) inputs[i] = ST(i + 1);
Branch: 1 branch
BranchTrueFalseTotal
for (i = 0; i < n; i++) inputs[i] = ST(i + 1); 15 9 24
276 9 pf_combine(aTHX_ G, mode, inputs, n);
277 9 Safefree(inputs);
278 9 RETVAL = G;
279 }
280 OUTPUT:
281 RETVAL
282  
283 # timer($secs): a future that settles after $secs (a loop timer, or a sleep
284 # off-loop). defer($cb): run $cb on the next tick; the future settles with its
285 # result. await: block until ready (pumping the loop), returning the future.
286 SV *
287 timer(class, secs)
288 SV *class
289 NV secs
290 CODE:
291 PERL_UNUSED_VAR(class);
292 2 RETVAL = pf_make_timer(aTHX_ (double)secs);
293 OUTPUT:
294 RETVAL
295  
296 SV *
297 defer(class, cb)
298 SV *class
299 SV *cb
300 CODE:
301 PERL_UNUSED_VAR(class);
302 1 RETVAL = pf_make_defer(aTHX_ cb);
303 OUTPUT:
304 RETVAL
305  
306 SV *
307 await(self)
308 SV *self
309 CODE:
310 0 pf_await(aTHX_ self);
311 0 RETVAL = newSVsv(self);
312 OUTPUT:
313 RETVAL
314  
315 # cancel: settle a pending future cancelled (its on_ready callbacks and any
316 # then-chain fire, the chain propagating the cancellation onward). Chains.
317 SV *
318 cancel(self)
319 SV *self
320 CODE:
321 {
322 15 punk_future *pf = pf_of(aTHX_ self);
323 15 ▶ if (pf->state == PF_PENDING) pf_settle(aTHX_ pf, self, PF_CANCELLED, NULL);
Branch: 1 branch
BranchTrueFalseTotal
if (pf->state == PF_PENDING) pf_settle(aTHX_ pf, self, PF_CANCELLED, NULL); 15 0 15
324 15 RETVAL = newSVsv(self);
325 }
326 OUTPUT:
327 RETVAL
328  
329 void
330 DESTROY(self)
331 SV *self
332 CODE:
333 395 pf_free(aTHX_ pf_of(aTHX_ self));
334  
335 MODULE = Punk PACKAGE = Punk::Context
336  
337 # Per-request conveniences: $c->promise (a new pending future), $c->timer($s) /
338 # $c->after($s) (a future settling after $s), and $c->await($f) (block for $f's
339 # result). They ignore $c - they exist where handler code already has it.
340 SV *
341 promise(self)
342 SV *self
343 CODE:
344 PERL_UNUSED_VAR(self);
345 2 RETVAL = pf_bless(aTHX_ pf_new(aTHX), "Punk::Future");
346 OUTPUT:
347 RETVAL
348  
349 SV *
350 timer(self, secs)
351 SV *self
352 NV secs
353 ALIAS:
354 after = 1
355 CODE:
356 PERL_UNUSED_VAR(self); PERL_UNUSED_VAR(ix);
357 3 RETVAL = pf_make_timer(aTHX_ (double)secs);
358 OUTPUT:
359 RETVAL
360  
361 void
362 await(self, f)
363 SV *self
364 SV *f
365 PPCODE:
366 {
367 punk_future *pf;
368 SSize_t i, n;
369 PERL_UNUSED_VAR(self);
370 4 pf = pf_of(aTHX_ f);
371 4 ▶ if (pf->state == PF_PENDING) pf_await(aTHX_ f);
Branch: 1 branch
BranchTrueFalseTotal
if (pf->state == PF_PENDING) pf_await(aTHX_ f); 0 4 4
372 4 SP = PL_stack_base + ax - 1; /* the loop ran: see get above */
373 4 ▶ if (pf->state == PF_CANCELLED) croak("Punk::Future: await on a cancelled future");
Branch: 1 branch
BranchTrueFalseTotal
if (pf->state == PF_CANCELLED) croak("Punk::Future: await on a cancelled future"); 0 4 4
374 4 ▶ if (pf->state == PF_FAILED) {
Branch: 1 branch
BranchTrueFalseTotal
if (pf->state == PF_FAILED) { 0 4 4
375 0 ▶ SV **fl = pf->vals ? av_fetch(pf->vals, 0, 0) : NULL;
Branch: 1 branch
BranchTrueFalseTotal
SV **fl = pf->vals ? av_fetch(pf->vals, 0, 0) : NULL; 0 0 0
376 0 ▶ croak_sv(fl && *fl ? *fl : sv_2mortal(newSVpvs("Punk::Future failed")));
Branch: 2 branches
BranchTrueFalseTotal
croak_sv(fl && *fl ? *fl : sv_2mortal(newSVpvs("Punk::Future failed"))); 0 0 0
croak_sv(fl && *fl ? *fl : sv_2mortal(newSVpvs("Punk::Future failed"))); 0 0 0
377 }
378 4 ▶ n = pf->vals ? av_len(pf->vals) + 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
n = pf->vals ? av_len(pf->vals) + 1 : 0; 4 0 4
379 4 ▶ EXTEND(SP, n);
Branch: 2 branches
BranchTrueFalseTotal
EXTEND(SP, n); 4 0 4
EXTEND(SP, n); 0 4 4
380 7 ▶ for (i = 0; i < n; i++) PUSHs(sv_2mortal(newSVsv(*av_fetch(pf->vals, i, 0))));
Branch: 1 branch
BranchTrueFalseTotal
for (i = 0; i < n; i++) PUSHs(sv_2mortal(newSVsv(*av_fetch(pf->vals, i, 0)))); 3 4 7
381 }
« xs/csp.xs ↑ Summary include/punk/punk_import.h »