1PERLMULTICORE.H(1) User Contributed Perl Documentation PERLMULTICORE.H(1)
2
6 perlmulticore.h - implements the Perl Multicore Specification
7
9 #include "perlmulticore.h"
10 // in your XS function:
12 perlinterp_release ();
14 do_the_C_thing ();
15 perlinterp_acquire ();
16
18 This documentation is the abridged version of the full documention at
19 <http://perlmulticore.schmorp.de/>. It's recommended to go there
20 instead of reading this document.
21 This header file implements a very low overhead (both in code and
23 runtime) mechanism for XS modules to allow re-use of the perl
24 interpreter for other threads while doing some lengthy operation, such
25 as cryptography, SQL queries, disk I/O and so on.
26 The newest version of the header file itself, can be downloaded from
28 <http://perlmulticore.schmorp.de/perlmulticore.h>.
29
31 The usage is very simple - you include this header file in your XS
32 module. Then, before you do your lengthy operation, you release the
33 perl interpreter:
34 perlinterp_release ();
36 And when you are done with your computation, you acquire it again:
38 perlinterp_acquire ();
40 And that's it. This doesn't load any modules and consists of only a few
42 machine instructions when no module to take advantage of it is loaded.
43 More documentation and examples can be found at the perl multicore site
45 at <http://perlmulticore.schmorp.de>.
46
48 As with everything, there are a number of rules to follow.
49 Never touch any perl data structures after calling
51 "perlinterp_release".
52 Anything perl is completely off-limits after "perlinterp_release",
53 until you call "perlinterp_acquire", after which you can access
54 perl stuff again.
55 That includes anything in the perl interpreter that you didn't
57 prove to be safe, and didn't prove to be safe in older and future
58 versions of perl: global variables, local perl scalars, even if you
59 are sure nobody accesses them and you only try to "read" their
60 value.
61 Always call "perlinterp_release" and "perlinterp_acquire" in pairs.
63 For each "perlinterp_release" call there must be a
64 "perlinterp_acquire" call. They don't have to be in the same
65 function, and you can have multiple calls to them, as long as every
66 "perlinterp_release" call is followed by exactly one
67 "perlinterp_acquire" call at runtime.
68 Never nest calls to "perlinterp_release" and "perlinterp_acquire".
70 That simply means that after calling "perlinterp_release", you must
71 call "perlinterp_acquire" before calling "perlinterp_release"
72 again. Likewise, after "perlinterp_acquire", you can call
73 "perlinterp_release" but not another "perlinterp_acquire".
74 Always call "perlinterp_release" first.
76 You must not call "perlinterp_acquire" without having called
77 "perlinterp_release" before.
78 Never underestimate threads.
80 While it's easy to add parallel execution ability to your XS
81 module, it doesn't mean it is safe. After you release the perl
82 interpreter, it's perfectly possible that it will call your XS
83 function in another thread, even while your original function still
84 executes. In other words: your C code must be thread safe, and if
85 you use any library, that library must be thread-safe, too.
86 Always assume that the code between "perlinterp_release" and
88 "perlinterp_acquire" is executed in parallel on multiple CPUs at
89 the same time.
90
92 You can disable the complete perl multicore API by defining the symbol
93 "PERL_MULTICORE_DISABLE" to 1 (e.g. by specifying
94 -DPERL_MULTICORE_DISABLE as compiler argument).
95 This could be added to perl's "CPPFLAGS" when configuring perl on
97 platforms that do not support threading at all for example.
98
100 Marc A. Lehmann <perlmulticore@schmorp.de>
101 http://perlmulticore.schmorp.de/
102
104 The perlmulticore.h header file is put into the public domain. Where
105 this is legally not possible, or at your option, it can be licensed
106 under creativecommons CC0 license:
107 <https://creativecommons.org/publicdomain/zero/1.0/>.
108perl v5.28.1 2019-02-02 PERLMULTICORE.H(1)