xs/bus.xs

filter: Statementstmt 100% 69 / 69 Branchbran 66.6% 56 / 84 (1 uncoverable) Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 81.7% 125 / 153 (1 uncoverable) CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« xs/abi.xs ↑ Summary include/hyperman/hm_sa_bus_perl.h »
1 MODULE = Hyperman PACKAGE = Hyperman
2  
3 PROTOTYPES: DISABLE
4  
5 # The cross-worker message bus, on a ring in the Shared::Arena.
6 #
7 # Class methods, matching deny_add / ratelimit_hit next door: the ring is
8 # process-global, so there is nothing to hold an object over, and an
9 # application that is not an XS module should not have to become one to reach
10 # it.
11 #
12 # TWO DELIVERY MODES, ONE MECHANISM. A message is published once; what differs
13 # is where the cursor lives. A FANOUT reader keeps its cursor in its own
14 # process, so every reader sees every message. A QUEUE GROUP keeps one cursor
15 # in the arena, advanced with a compare-and-swap, so exactly one member of the
16 # pool sees each message.
17  
18 # bus_init(slots => N, slot_size => N, groups => N, wakers => N) -> 1 if
19 # there is a ring
20 #
21 # run() does this before it forks, which is the only place it can be done: a
22 # ring created after the fork is one ring per worker, which is a bus that
23 # delivers to nobody. This is here for a script or a test that forks by hand
24 # and needs the same guarantee. Idempotent - the first call wins, so calling
25 # it after the server has started changes nothing. With no arena yet, the
26 # default one is created first. `groups` is accepted and ignored: the ring's
27 # group table is fixed at 64.
28 IV
29 bus_init(class, ...)
30 SV *class
31 CODE:
32 {
33 4 UV slots = 0, slot_size = 0, groups = 0, wakers = 0;
34 4 int i, err = 0;
35 PERL_UNUSED_VAR(class);
36 16 ▶ for (i = 1; i + 1 < items; i += 2) {
Branch: 1 branch
BranchTrueFalseTotal
for (i = 1; i + 1 < items; i += 2) { 12 4 16
37 12 const char *k = SvPV_nolen(ST(i));
38 12 ▶ if (strEQ(k, "slots")) slots = SvUV(ST(i + 1));
Branch: 1 branch
BranchTrueFalseTotal
if (strEQ(k, "slots")) slots = SvUV(ST(i + 1)); 4 8 12
39 8 ▶ else if (strEQ(k, "slot_size")) slot_size = SvUV(ST(i + 1));
Branch: 1 branch
BranchTrueFalseTotal
else if (strEQ(k, "slot_size")) slot_size = SvUV(ST(i + 1)); 4 4 8
40 4 ▶ else if (strEQ(k, "groups")) groups = SvUV(ST(i + 1));
Branch: 1 branch
BranchTrueFalseTotal
else if (strEQ(k, "groups")) groups = SvUV(ST(i + 1)); 2 2 4
41 2 ▶ # uncoverable branch false class:ignore_covered_err
Branch: 1 branch
BranchTrueFalseTotal
# uncoverable branch false class:ignore_covered_err 2 0 2
42 # uncoverable condition right count:1 class:ignore_covered_err
43 else if (strEQ(k, "wakers")) wakers = SvUV(ST(i + 1));
44 4 }
45 PERL_UNUSED_VAR(groups);
46 4 hm_sa_open(aTHX_ NULL, 0,
47 hm_sa_bytes(0, 0, (unsigned)slots, (unsigned)slot_size));
48 (void)hm_sa_bus_open((uint32_t)slots, (uint32_t)slot_size, &err);
49 /* The wakeup descriptors go with the ring and for the same reason:
50 4 ▶ * made before any fork, or a worker's poke reaches nobody. run()
Branch: 1 branch
BranchTrueFalseTotal
* made before any fork, or a worker's poke reaches nobody. run() 2 2 4
51 4 ▶ * sizes this from the worker count. */
Branch: 1 branch
BranchTrueFalseTotal
* sizes this from the worker count. */ 0 4 4
52 (void)hm_sa_bus_wake_init((uint32_t)(wakers ? wakers : 8));
53 RETVAL = hm_sa_bus_live() ? 1 : 0; /* # uncoverable condition left count:1 class:ignore_covered_err */
54 }
55 OUTPUT:
56 RETVAL
57  
58 # Is there a shared ring at all?
59 #
60 # Ask before assuming the pool can hear you. With no ring - Shared::Arena
61 # absent, a compiler without atomics, or simply not running under Hyperman -
62 # publish reaches this process only. That is a supported configuration and
63 # the tested path, not a broken one.
64 IV
65 bus_live(class = &PL_sv_undef)
66 SV *class
67 CODE:
68 PERL_UNUSED_VAR(class);
69 1 ▶ RETVAL = hm_sa_bus_live() ? 1 : 0; /* # uncoverable condition left count:1 class:ignore_covered_err */
Branch: 1 branch
BranchTrueFalseTotal
RETVAL = hm_sa_bus_live() ? 1 : 0; /* # uncoverable condition left count:1 class:ignore_covered_err */ 0 1 1
70 OUTPUT:
71 RETVAL
72  
73 # publish($topic, $payload)
74 #
75 # 1 on the ring, and the whole pool will see it
76 # 0 LOCAL ONLY - there is no ring, so nobody else will
77 # -1 refused: too big for a slot
78 #
79 # Three outcomes rather than true/false, because "sent to the pool" and "sent
80 # to myself" are different things and a caller that cannot tell them apart
81 # cannot diagnose anything.
82 #
83 # An oversize message is REFUSED, never truncated. A truncated WebSocket frame
84 # is a protocol violation delivered to every member of a room, which is worse
85 # than a publish that failed where the caller can see it. Raise bus_slot_size
86 # when the messages are genuinely that big.
87 IV
88 publish(class, topic, payload)
89 SV *class
90 SV *topic
91 SV *payload
92 CODE:
93 {
94 STRLEN tl, pl;
95 21503 ▶ const char *t = SvPV_const(topic, tl);
Branch: 1 branch
BranchTrueFalseTotal
const char *t = SvPV_const(topic, tl); 226 21277 21503
96 21503 const char *p = SvPV_const(payload, pl);
97 21503 int r = hm_sa_bus_publish(t, (uint32_t)tl, p, (uint32_t)pl);
98 PERL_UNUSED_VAR(class);
99 21503 ▶ RETVAL = (r == HM_BUS_OK) ? 1 : (r == HM_BUS_LOCAL) ? 0 : -1; /* # uncoverable condition left count:2 class:ignore_covered_err */
Branch: 3 branches
BranchTrueFalseTotal
RETVAL = (r == HM_BUS_OK) ? 1 : (r == HM_BUS_LOCAL) ? 0 : -1; /* # uncoverable condition left count:2 class:ignore_covered_err */ 2 21501 21503
RETVAL = (r == HM_BUS_OK) ? 1 : (r == HM_BUS_LOCAL) ? 0 : -1; /* # uncoverable condition left count:2 class:ignore_covered_err */ 0 2 2
RETVAL = (r == HM_BUS_OK) ? 1 : (r == HM_BUS_LOCAL) ? 0 : -1; /* # uncoverable condition left count:2 class:ignore_covered_err */ 21474 29 21503
100 }
101 OUTPUT:
102 RETVAL
103  
104 # bus_reset() -> the sequence it reset to
105 #
106 # Point this process's fanout cursors at "from now on". A WORKER MUST CALL
107 # THIS AFTER A FORK: a cursor inherited from the parent either replays what
108 # the parent already delivered or skips what it has not, and both look like
109 # the bus being broken. on_worker_start is the place.
110 #
111 # BOTH cursors. There are two - one for receive(), one for the subscription
112 # dispatcher - because two readers in one process must not consume each
113 # other's messages. But a caller saying "from now on" means the process, not
114 # one of its two halves, and resetting only one leaves the other replaying.
115 IV
116 bus_reset(class = &PL_sv_undef)
117 SV *class
118 CODE:
119 PERL_UNUSED_VAR(class);
120 5 hm_sa_bus_reset_cursors();
121 5 ▶ RETVAL = (IV)hm_sa_bus_seq();
Branch: 1 branch
BranchTrueFalseTotal
RETVAL = (IV)hm_sa_bus_seq(); 0 5 5
122 OUTPUT:
123 RETVAL
124  
125 # receive() -> ( [topic, payload], ... )
126 #
127 # Everything published since this process last asked. FANOUT: the cursor is
128 # this process's own, so every reader gets every message.
129 #
130 # Returns the empty list when there is nothing, which is the common case and
131 # costs one atomic load.
132 void
133 receive(class = &PL_sv_undef)
134 SV *class
135 PPCODE:
136 {
137 6 AV *out = (AV *)sv_2mortal((SV *)newAV());
138 SSize_t i, n;
139 PERL_UNUSED_VAR(class);
140 6 (void)hm_sa_bus_drain(&hm_sa_recv_cur, hm_bus_perl_collect, out);
141 6 n = av_len(out) + 1;
142 6 ▶ EXTEND(SP, n);
Branch: 2 branches
BranchTrueFalseTotal
EXTEND(SP, n); 6 0 6
EXTEND(SP, n); 0 6 6
143 72 ▶ for (i = 0; i < n; i++) {
Branch: 1 branch
BranchTrueFalseTotal
for (i = 0; i < n; i++) { 66 6 72
144 66 SV **e = av_fetch(out, i, 0);
145 66 ▶ # uncoverable condition right count:1 class:ignore_covered_err
Branch: 2 branches
BranchTrueFalseTotal
# uncoverable condition right count:1 class:ignore_covered_err 66 0 66
# uncoverable condition right count:1 class:ignore_covered_err 66 0 66
146 # uncoverable condition right count:2 class:ignore_covered_err
147 PUSHs(e && *e ? sv_2mortal(newSVsv(*e)) : &PL_sv_undef);
148 }
149 }
150  
151 # How many messages this process MISSED, because it did not read them before
152 # the ring wrapped past them, or because a publisher died leaving a hole.
153 #
154 # Reporting this is not optional. A silently short chat room is
155 # indistinguishable from a quiet one; a gap with a number beside it is a
156 # diagnosis. If this is climbing, the reader is too slow or bus_slots is too
157 # small.
158 #
159 # BOTH cursors, because this answers a question about the PROCESS. There are
160 # two readers - receive() has its own cursor, the dispatcher that feeds
161 # subscribe() has another - and this used to report only receive()'s. Under a
162 # server nothing calls receive(), so the number was always zero however much
163 # the dispatcher dropped: the one place a short count had to be explained was
164 # the one place the counter could not see.
165 IV
166 bus_gaps(class = &PL_sv_undef)
167 SV *class
168 CODE:
169 PERL_UNUSED_VAR(class);
170 3 RETVAL = (IV)(hm_sa_bus_gaps_of(hm_sa_recv_cur)
171 3 ▶ + hm_sa_bus_gaps_of(hm_sa_disp_cur));
Branch: 1 branch
BranchTrueFalseTotal
+ hm_sa_bus_gaps_of(hm_sa_disp_cur)); 0 3 3
172 OUTPUT:
173 RETVAL
174  
175 # claim($topic, $group) -> ( [topic, payload], ... )
176 #
177 # A QUEUE GROUP: whatever nobody else in the pool has taken. One
178 # compare-and-swap on the group's shared cursor hands each message to exactly
179 # one caller, in one process, across every worker.
180 #
181 # Balancing is not implemented, it is a consequence: a worker that is busy is
182 # not in this call, so it does not claim, so the free workers take the
183 # traffic. There is no scheduler and nothing to tune.
184 #
185 # AT-MOST-ONCE. A worker that claims a message and then dies loses it, and the
186 # loss is counted rather than retried. If losing it matters, this is the wrong
187 # tool and Punk::Queue is the right one.
188 #
189 # The group is created on first use and starts at the current sequence:
190 # joining means "from now on", not "replay everything".
191 #
192 # A group is bound to its TOPIC, and the identity is the pair. Without that a
193 # group would claim every message on the ring whatever its topic, mark it
194 # handled, and the intended reader would never see it. $group defaults to the
195 # topic, which is what a single group per topic wants.
196 void
197 claim(class, topic, group = &PL_sv_undef)
198 SV *class
199 SV *topic
200 SV *group
201 PPCODE:
202 {
203 7 AV *out = (AV *)sv_2mortal((SV *)newAV());
204 STRLEN tl, gl;
205 7 const char *t = SvPV_const(topic, tl);
206 14 ▶ const char *g = SvOK(group) ? SvPV_const(group, gl) : (gl = tl, t); /* # uncoverable condition right count:1 class:ignore_covered_err */
Branch: 1 branch
BranchTrueFalseTotal
const char *g = SvOK(group) ? SvPV_const(group, gl) : (gl = tl, t); /* # uncoverable condition right count:1 class:ignore_covered_err */ 7 0 7
207 7 sa_group_h *gh = hm_sa_bus_group(t, (uint32_t)tl, g, (uint32_t)gl);
208 SSize_t i, n;
209 PERL_UNUSED_VAR(class);
210 7 ▶ # uncoverable branch true class:ignore_covered_err
Branch: 1 branch
BranchTrueFalseTotal
# uncoverable branch true class:ignore_covered_err 0 7 7
211 7 # uncoverable condition left count:1 class:ignore_covered_err
212 7 if (!gh) XSRETURN_EMPTY; /* no ring, or the table is full */
213 7 ▶ (void)hm_sa_bus_claim(gh, hm_bus_perl_collect, out);
Branch: 2 branches
BranchTrueFalseTotal
(void)hm_sa_bus_claim(gh, hm_bus_perl_collect, out); 7 0 7
(void)hm_sa_bus_claim(gh, hm_bus_perl_collect, out); 0 7 7
214 13 ▶ n = av_len(out) + 1;
Branch: 1 branch
BranchTrueFalseTotal
n = av_len(out) + 1; 6 7 13
215 6 EXTEND(SP, n);
216 6 ▶ for (i = 0; i < n; i++) {
Branch: 2 branches
BranchTrueFalseTotal
for (i = 0; i < n; i++) { 6 0 6
for (i = 0; i < n; i++) { 6 0 6
217 SV **e = av_fetch(out, i, 0);
218 # uncoverable condition right count:1 class:ignore_covered_err
219 # uncoverable condition right count:2 class:ignore_covered_err
220 PUSHs(e && *e ? sv_2mortal(newSVsv(*e)) : &PL_sv_undef);
221 }
222 }
223  
224 # subscribe($topic, $cb, group => $name) -> an id, or -1
225 #
226 # The callback is invoked as $cb->($topic, $payload) from the worker's event
227 # loop, as soon as a publish from any worker pokes this one. No polling, and
228 # no Perl frame on the publishing side.
229 #
230 # `group` is the ONLY difference between the two delivery modes. Without it
231 # this process sees every message on the topic. With it, this process competes
232 # with every other member of that group and exactly one of them sees each
233 # message - load balanced, with no scheduler, because a busy worker is not in
234 # the loop to claim.
235 #
236 # A subscriber that dies gets its death turned into a warning: it runs from the
237 # event loop with nothing to unwind into, and one bad handler must not remove a
238 # worker from the pool.
239 IV
240 subscribe(class, topic, cb, ...)
241 SV *class
242 SV *topic
243 SV *cb
244 CODE:
245 {
246 10 STRLEN tl, gl = 0;
247 10 const char *t = SvPV_const(topic, tl);
248 10 const char *g = NULL;
249 int i, id;
250 PERL_UNUSED_VAR(class);
251 10 ▶ if (!(SvROK(cb) && SvTYPE(SvRV(cb)) == SVt_PVCV)) /* # uncoverable condition left count:2 class:ignore_covered_err */
Branch: 2 branches
BranchTrueFalseTotal
if (!(SvROK(cb) && SvTYPE(SvRV(cb)) == SVt_PVCV)) /* # uncoverable condition left count:2 class:ignore_covered_err */ 9 1 10
if (!(SvROK(cb) && SvTYPE(SvRV(cb)) == SVt_PVCV)) /* # uncoverable condition left count:2 class:ignore_covered_err */ 0 9 9
252 1 croak("Hyperman->subscribe: need a code reference");
253 10 ▶ for (i = 3; i + 1 < items; i += 2) {
Branch: 1 branch
BranchTrueFalseTotal
for (i = 3; i + 1 < items; i += 2) { 1 9 10
254 1 const char *k = SvPV_nolen(ST(i));
255 1 ▶ # uncoverable branch false class:ignore_covered_err
Branch: 2 branches
BranchTrueFalseTotal
# uncoverable branch false class:ignore_covered_err 1 0 1
# uncoverable branch false class:ignore_covered_err 1 0 1
256 2 # uncoverable condition right count:1 class:ignore_covered_err
257 # uncoverable condition right count:2 class:ignore_covered_err
258 9 if (strEQ(k, "group") && SvOK(ST(i + 1)))
259 g = SvPV_const(ST(i + 1), gl);
260 9 ▶ }
Branch: 1 branch
BranchTrueFalseTotal
} 0 9 9
261 9 ▶ id = hm_sa_bus_subscribe(t, (uint32_t)tl, g, (uint32_t)gl,
Branch: 1 branch
BranchTrueFalseTotal
id = hm_sa_bus_subscribe(t, (uint32_t)tl, g, (uint32_t)gl, 0 9 9
262 9 hm_bus_perl_deliver, NULL);
263 9 # uncoverable branch true class:ignore_covered_err
264 9 ▶ # uncoverable condition left count:1 class:ignore_covered_err
Branch: 1 branch
BranchTrueFalseTotal
# uncoverable condition left count:1 class:ignore_covered_err 0 9 9
265 if (id < 0) XSRETURN_IV(-1);
266 # uncoverable statement class:ignore_covered_err
267 # uncoverable branch true
268 # uncoverable condition left count:1
269 if (hm_bus_perl_subs[id]) SvREFCNT_dec(hm_bus_perl_subs[id]);
270 hm_bus_perl_subs[id] = newSVsv(cb);
271 hm_bus_subs[id].ud = (void *)hm_bus_perl_subs[id];
272 RETVAL = id;
273 }
274 OUTPUT:
275 RETVAL
276  
277 IV
278 unsubscribe(class, id)
279 SV *class
280 IV id
281 CODE:
282 {
283 PERL_UNUSED_VAR(class);
284 6 ▶ # uncoverable branch false class:ignore_covered_err
Branch: 3 branches
BranchTrueFalseTotal
# uncoverable branch false class:ignore_covered_err 6 0 6
# uncoverable branch false class:ignore_covered_err 6 0 6
# uncoverable branch false class:ignore_covered_err 6 0 6
285 6 # uncoverable condition right count:1 class:ignore_covered_err
286 6 # uncoverable condition right count:2 class:ignore_covered_err
287 # uncoverable condition right count:3 class:ignore_covered_err
288 6 ▶ if (id >= 0 && id < HM_BUS_SUBS && hm_bus_perl_subs[id]) {
Branch: 1 branch
BranchTrueFalseTotal
if (id >= 0 && id < HM_BUS_SUBS && hm_bus_perl_subs[id]) { 2 4 6
289 SvREFCNT_dec(hm_bus_perl_subs[id]);
290 hm_bus_perl_subs[id] = NULL;
291 }
292 RETVAL = hm_sa_bus_unsubscribe((int)id);
293 }
294 OUTPUT:
295 RETVAL
296  
297 # dispatch() -> how many were delivered
298 #
299 # Runs the subscriptions by hand. Under a Hyperman worker the wakeup does this
300 # and a caller never needs to; outside one - a script, a test, a server that is
301 # not Hyperman - this is the poll that stands in for it. It never blocks: a
302 # record still being written is left for the next call.
303 IV
304 dispatch(class = &PL_sv_undef)
305 SV *class
306 CODE:
307 PERL_UNUSED_VAR(class);
308 6 RETVAL = (IV)hm_sa_bus_dispatch();
309 OUTPUT:
310 RETVAL
311  
312 # bus_waker_take($index) -> this process's wakeup descriptor, or -1
313 #
314 # A worker calls this after the fork, with its own worker number, so no two
315 # workers share a descriptor. Under a Hyperman server the server does it; this
316 # is here for a process that forks by hand, and for the tests, which have to
317 # be able to block on the descriptor the way an event loop does.
318 IV
319 bus_waker_take(class, idx)
320 SV *class
321 IV idx
322 CODE:
323 PERL_UNUSED_VAR(class);
324 1 ▶ RETVAL = hm_sa_bus_waker_take((int)idx);
Branch: 1 branch
BranchTrueFalseTotal
RETVAL = hm_sa_bus_waker_take((int)idx); 0 1 1
325 OUTPUT:
326 RETVAL
327  
328 # Empty the poke and clear the coalescing flag. Called before dispatching, so
329 # a publish that lands DURING the dispatch pokes again rather than being folded
330 # into a wakeup that has already been handled.
331 void
332 bus_waker_drained(class = &PL_sv_undef)
333 SV *class
334 CODE:
335 PERL_UNUSED_VAR(class);
336 1 hm_sa_bus_waker_drained();
337  
338 # bus_stats() -> ( published => N, gaps => N, group_gaps => N )
339 #
340 # `gaps` is this process's; `group_gaps` belongs to the named group and is
341 # shared, because a message lapped before anybody claimed it was lost by the
342 # group rather than by whichever member noticed. The group is the one
343 # claim($group) without a topic would use: named after its topic.
344 void
345 bus_stats(class, group = &PL_sv_undef)
346 SV *class
347 SV *group
348 PPCODE:
349 {
350 PERL_UNUSED_VAR(class);
351 5 ▶ EXTEND(SP, 6);
Branch: 1 branch
BranchTrueFalseTotal
EXTEND(SP, 6); 0 5 5
352 5 mPUSHp("published", 9); mPUSHu((UV)hm_sa_bus_published());
353 /* Both cursors, for the reason bus_gaps says. */
354 5 mPUSHp("gaps", 4); mPUSHu((UV)(hm_sa_bus_gaps_of(hm_sa_recv_cur)
355 + hm_sa_bus_gaps_of(hm_sa_disp_cur)));
356 5 ▶ if (SvOK(group)) {
Branch: 1 branch
BranchTrueFalseTotal
if (SvOK(group)) { 3 2 5
357 STRLEN gl;
358 3 const char *g = SvPV_const(group, gl);
359 3 sa_group_h *gh = hm_sa_bus_group(g, (uint32_t)gl, g, (uint32_t)gl);
360 3 mPUSHp("group_gaps", 10);
361 3 ▶ mPUSHu(gh ? (UV)hm_sa_bus_group_gaps(gh) : 0); /* # uncoverable condition right count:1 class:ignore_covered_err */
Branch: 1 branch
BranchTrueFalseTotal
mPUSHu(gh ? (UV)hm_sa_bus_group_gaps(gh) : 0); /* # uncoverable condition right count:1 class:ignore_covered_err */ 3 0 3
362 }
363 }
« xs/abi.xs ↑ Summary include/hyperman/hm_sa_bus_perl.h »