include/hyperman/hyperman.h

filter: Statementstmt 93.3% 14 / 15 Branchbran 100% 4 / 8 (4 uncoverable) Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 95.6% 18 / 23 (4 uncoverable) CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« include/hyperman/hm_win.h ↑ Summary blib/lib/Hyperman.pm »
1 #ifndef HYPERMAN_H
2 #define HYPERMAN_H
3  
4 /* Hyperman - shared types for the event loop core and its pluggable
5 * readiness backends. The backend wraps the OS
6 * mechanism (kqueue now, epoll later) behind add/modify/remove/wait; the
7 * loop core and HTTP/PSGI machinery live in Hyperman.xs. */
8  
9 #include <stddef.h>
10 #include <stdint.h>
11 #include <time.h>
12  
13 #define HM_MAXFD 65536
14 #define HM_MAXEV 1024
15 #define HM_RBUF 16384
16  
17 /* interest / event kinds */
18 #define HM_EV_READ 0x1
19 #define HM_EV_WRITE 0x2
20 #define HM_EV_TIMER 0x4
21 #define HM_EV_SIGNAL 0x8
22 /* A COMPLETION, not a readiness: the read the core asked for has already
23 * happened and the bytes are in the buffer it supplied. Only a backend that
24 * implements submit_recv ever produces these. */
25 #define HM_EV_RECV 0x10
26  
27 /* one normalized event out of the backend - readiness, or a completion */
28 typedef struct {
29 int kind; /* HM_EV_* */
30 int fd; /* READ/WRITE: the fd; SIGNAL: signo */
31 void *udata; /* TIMER: the watcher registered with add_timer */
32 int res; /* RECV: bytes read, 0 = EOF, <0 = -errno */
33 uint64_t token; /* RECV: whatever the core passed to submit_recv */
34 } hm_event;
35  
36 /* Backend interface: add($fd,$mask) / modify / remove /
37 * wait($timeout) -> @ready. Timers and signals are watcher-style adds. */
38 typedef struct hm_backend hm_backend;
39 struct hm_backend {
40 const char *name;
41 void *state;
42 /* Set when this backend was inherited across a fork: destroy() then
43 * releases its memory but closes NO descriptor, because none of them
44 * belong to this process. A kqueue does not even survive fork - the
45 * kernel invalidates the child's copy, so the number is free and the
46 * child's own kqueue() is handed it straight back; closing it there
47 * would shut the queue the child is actually using. */
48 int foreign;
49 int (*add_io) (hm_backend *, int fd, int mask, int oneshot);
50 int (*modify_io) (hm_backend *, int fd, int mask, int oneshot);
51 int (*remove_io) (hm_backend *, int fd, int mask);
52 int (*add_timer) (hm_backend *, double secs, int oneshot, void *udata);
53 int (*del_timer) (hm_backend *, void *udata);
54 int (*add_signal)(hm_backend *, int signo);
55 /* timeout < 0 waits forever; returns count or -1 (errno) */
56 int (*wait) (hm_backend *, hm_event *out, int max, double timeout);
57 void (*destroy) (hm_backend *);
58  
59 /* ---- optional: completion-based receive ----------------------------
60 *
61 * NULL on a readiness backend, which is all of them but io_uring - the
62 * core then reads for itself exactly as it always has, and none of this
63 * is reachable. The whole point of the vtable staying a superset is that
64 * kqueue, epoll, poll and wsapoll are not touched by any of it.
65 *
66 * submit_recv asks for ONE read of up to len bytes into buf, delivered
67 * later as an HM_EV_RECV carrying `token` back. The buffer must stay put
68 * and untouched until that completion arrives - the kernel writes into it
69 * whenever it likes.
70 *
71 * `token` is opaque here on purpose. The core puts an fd-plus-generation
72 * in it, because a completion can outlive the connection that asked for
73 * it: the fd may be closed and REUSED before the kernel gets round to
74 * it, and a bare fd would then deliver another connection's bytes to
75 * whoever now holds that number.
76 *
77 * Returns 0 if submitted, -1 if not (the core falls back to reading).
78 *
79 * cancel_recv drops an in-flight read at close. It is best-effort: a
80 * completion may already be on its way, which is what the generation in
81 * the token is for. */
82 int (*submit_recv)(hm_backend *, int fd, void *buf, size_t len,
83 uint64_t token);
84 void (*cancel_recv)(hm_backend *, int fd);
85 };
86  
87 hm_backend *hm_backend_kqueue_new(void);
88 int hm_backend_kqueue_available(void);
89 hm_backend *hm_backend_epoll_new(void);
90 int hm_backend_epoll_available(void);
91 hm_backend *hm_backend_poll_new(void);
92 int hm_backend_poll_available(void);
93 hm_backend *hm_backend_wsapoll_new(void);
94 int hm_backend_wsapoll_available(void);
95 hm_backend *hm_backend_iouring_new(void);
96 int hm_backend_iouring_available(void);
97  
98 /* pick by name ("kqueue"/"epoll"/"poll"), or best-available when NULL */
99 hm_backend *hm_backend_create(const char *name);
100  
101 /* Allocation wrappers used throughout the core, backends and XS glue. An
102 * out-of-memory result croaks (noreturn) rather than returning NULL, so no
103 * caller has to null-check a hot-path allocation. Compiled in the single
104 * Hyperman unity translation unit, after perl.h. */
105 #include <stdlib.h>
106  
107 /* A forked child leaves by _exit, which runs no atexit handler: under a
108 * coverage build its counters would be lost with it. The gcov runtime's dump
109 * is bound weakly, so an ordinary build resolves it to nothing and skips it. */
110 #if (defined(__GNUC__) || defined(__clang__)) && !defined(_WIN32)
111 #include <unistd.h>
112 extern void __gcov_dump(void) __attribute__((weak));
113 84 static void hm_exit(int status) {
114 /*
115 # uncoverable branch false class:ignore_covered_err
116 # uncoverable condition right count:1 class:ignore_covered_err */
117 84 ▶ if (__gcov_dump) __gcov_dump();
Branch: 1 branch
BranchTrueFalseTotal
if (__gcov_dump) __gcov_dump(); 84 0 84
118 0 _exit(status); /* # uncoverable statement class:ignore_covered_err */
119 }
120 #else
121 #define hm_exit(status) _exit(status)
122 #endif
123  
124 28167 static void *hm_xmalloc(size_t n) {
125 28167 void *p = malloc(n);
126 /*
127 # uncoverable branch true
128 # uncoverable condition left count:1 class:ignore_covered_err */
129 28167 ▶ if (!p) Perl_croak_nocontext("Hyperman: out of memory (%llu bytes)",
Branch: 1 branch
BranchTrueFalseTotal
if (!p) Perl_croak_nocontext("Hyperman: out of memory (%llu bytes)", 0 28167 28167
130 (unsigned long long)n); /* # uncoverable statement */
131 28167 return p;
132 }
133 82745 static void *hm_xcalloc(size_t count, size_t size) {
134 82745 void *p = calloc(count, size);
135 /*
136 # uncoverable branch true
137 # uncoverable condition left count:1 class:ignore_covered_err */
138 82745 ▶ if (!p) Perl_croak_nocontext("Hyperman: out of memory (%llu x %llu bytes)",
Branch: 1 branch
BranchTrueFalseTotal
if (!p) Perl_croak_nocontext("Hyperman: out of memory (%llu x %llu bytes)", 0 82745 82745
139 (unsigned long long)count, (unsigned long long)size); /* # uncoverable statement */
140 82745 return p;
141 }
142 391 static void *hm_xrealloc(void *old, size_t n) {
143 391 void *p = realloc(old, n);
144 /*
145 # uncoverable branch true
146 # uncoverable condition left count:1 class:ignore_covered_err */
147 391 ▶ if (!p) Perl_croak_nocontext("Hyperman: out of memory (%llu bytes)",
Branch: 1 branch
BranchTrueFalseTotal
if (!p) Perl_croak_nocontext("Hyperman: out of memory (%llu bytes)", 0 391 391
148 (unsigned long long)n); /* # uncoverable statement */
149 391 return p;
150 }
151  
152 #endif
« include/hyperman/hm_win.h ↑ Summary blib/lib/Hyperman.pm »