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 // optional, in BOOT section:
18 perlmulticore_support ();
20
22 This documentation is the abridged version of the full documention at
23 <http://perlmulticore.schmorp.de/>. It's recommended to go there
24 instead of reading this document.
25 This header file implements a very low overhead (both in code and
27 runtime) mechanism for XS modules to allow re-use of the perl
28 interpreter for other threads while doing some lengthy operation, such
29 as cryptography, SQL queries, disk I/O and so on.
30 The newest version of the header file itself, can be downloaded from
32 <http://perlmulticore.schmorp.de/perlmulticore.h>.
33
35 The usage is very simple - you include this header file in your XS
36 module. Then, before you do your lengthy operation, you release the
37 perl interpreter:
38 perlinterp_release ();
40 And when you are done with your computation, you acquire it again:
42 perlinterp_acquire ();
44 And that's it. This doesn't load any modules and consists of only a few
46 machine instructions when no module to take advantage of it is loaded.
47 More documentation and examples can be found at the perl multicore site
49 at <http://perlmulticore.schmorp.de>.
50
52 As with everything, there are a number of rules to follow.
53 Never touch any perl data structures after calling
55 "perlinterp_release".
56 Anything perl is completely off-limits after "perlinterp_release",
57 until you call "perlinterp_acquire", after which you can access
58 perl stuff again.
59 That includes anything in the perl interpreter that you didn't
61 prove to be safe, and didn't prove to be safe in older and future
62 versions of perl: global variables, local perl scalars, even if you
63 are sure nobody accesses them and you only try to "read" their
64 value.
65 Always call "perlinterp_release" and "perlinterp_acquire" in pairs.
67 For each "perlinterp_release" call there must be a
68 "perlinterp_acquire" call. They don't have to be in the same
69 function, and you can have multiple calls to them, as long as every
70 "perlinterp_release" call is followed by exactly one
71 "perlinterp_acquire" call at runtime.
72 Never nest calls to "perlinterp_release" and "perlinterp_acquire".
74 That simply means that after calling "perlinterp_release", you must
75 call "perlinterp_acquire" before calling "perlinterp_release"
76 again. Likewise, after "perlinterp_acquire", you can call
77 "perlinterp_release" but not another "perlinterp_acquire".
78 Always call "perlinterp_release" first.
80 You must not call "perlinterp_acquire" without having called
81 "perlinterp_release" before.
82 Never underestimate threads.
84 While it's easy to add parallel execution ability to your XS
85 module, it doesn't mean it is safe. After you release the perl
86 interpreter, it's perfectly possible that it will call your XS
87 function in another thread, even while your original function still
88 executes. In other words: your C code must be thread safe, and if
89 you use any library, that library must be thread-safe, too.
90 Always assume that the code between "perlinterp_release" and
92 "perlinterp_acquire" is executed in parallel on multiple CPUs at
93 the same time.
94
96 You can disable the complete perl multicore API by defining the symbol
97 "PERL_MULTICORE_DISABLE" to 1 (e.g. by specifying
98 -DPERL_MULTICORE_DISABLE as compiler argument).
99 This could be added to perl's "CPPFLAGS" when configuring perl on
101 platforms that do not support threading at all for example.
102
104 To help users find out whether a particular build of your module is, in
105 fact, multicore enabled, you can invoke the "perlmulticore_support"
106 macro in your "BOOT:" section, e.g.:
107 MODULE = My::Mod PACKAGE = My::Mod::Pkg
109 BOOT:
111 perlmulticore_support ();
112 What this does is set the $My::Mod::PERLMULTICORE_SUPPORT variable to
114 the major API version * 1000 + minor version, for example, version 1002
115 introduced this feature.
116 For this to work, the "cv" parameter passed to "BOOT:" must still be in
118 scope. To ensure this, either invoke the macro early in your "BOOT:"
119 section, or don't declare a local variable called "cv", either of which
120 should be easy to do.
121 Note that this is optional, so you don't have to do that.
123
125 Marc A. Lehmann <perlmulticore@schmorp.de>
126 http://perlmulticore.schmorp.de/
127
129 The perlmulticore.h header file is put into the public domain. Where
130 this is legally not possible, or at your option, it can be licensed
131 under creativecommons CC0 license:
132 <https://creativecommons.org/publicdomain/zero/1.0/>.
133perl v5.30.1 2020-01-29 PERLMULTICORE.H(1)