1PERLEMBED(1) Perl Programmers Reference Guide PERLEMBED(1)
2
3
4
6 perlembed - how to embed perl in your C program
7
9 PREAMBLE
10 Do you want to:
11
12 Use C from Perl?
13 Read perlxstut, perlxs, h2xs, perlguts, and perlapi.
14
15 Use a Unix program from Perl?
16 Read about back-quotes and about "system" and "exec" in perlfunc.
17
18 Use Perl from Perl?
19 Read about "do" in perlfunc and "eval" in perlfunc and "require"
20 in perlfunc and "use" in perlfunc.
21
22 Use C from C?
23 Rethink your design.
24
25 Use Perl from C?
26 Read on...
27
28 ROADMAP
29 · Compiling your C program
30
31 · Adding a Perl interpreter to your C program
32
33 · Calling a Perl subroutine from your C program
34
35 · Evaluating a Perl statement from your C program
36
37 · Performing Perl pattern matches and substitutions from your C
38 program
39
40 · Fiddling with the Perl stack from your C program
41
42 · Maintaining a persistent interpreter
43
44 · Maintaining multiple interpreter instances
45
46 · Using Perl modules, which themselves use C libraries, from your C
47 program
48
49 · Embedding Perl under Win32
50
51 Compiling your C program
52 If you have trouble compiling the scripts in this documentation, you're
53 not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY THE SAME
54 WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.)
55
56 Also, every C program that uses Perl must link in the perl library.
57 What's that, you ask? Perl is itself written in C; the perl library is
58 the collection of compiled C programs that were used to create your
59 perl executable (/usr/bin/perl or equivalent). (Corollary: you can't
60 use Perl from your C program unless Perl has been compiled on your
61 machine, or installed properly--that's why you shouldn't blithely copy
62 Perl executables from machine to machine without also copying the lib
63 directory.)
64
65 When you use Perl from C, your C program will--usually--allocate,
66 "run", and deallocate a PerlInterpreter object, which is defined by the
67 perl library.
68
69 If your copy of Perl is recent enough to contain this documentation
70 (version 5.002 or later), then the perl library (and EXTERN.h and
71 perl.h, which you'll also need) will reside in a directory that looks
72 like this:
73
74 /usr/local/lib/perl5/your_architecture_here/CORE
75
76 or perhaps just
77
78 /usr/local/lib/perl5/CORE
79
80 or maybe something like
81
82 /usr/opt/perl5/CORE
83
84 Execute this statement for a hint about where to find CORE:
85
86 perl -MConfig -e 'print $Config{archlib}'
87
88 Here's how you'd compile the example in the next section, "Adding a
89 Perl interpreter to your C program", on my Linux box:
90
91 % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
92 -I/usr/local/lib/perl5/i586-linux/5.003/CORE
93 -L/usr/local/lib/perl5/i586-linux/5.003/CORE
94 -o interp interp.c -lperl -lm
95
96 (That's all one line.) On my DEC Alpha running old 5.003_05, the
97 incantation is a bit different:
98
99 % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
100 -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
101 -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
102 -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm
103
104 How can you figure out what to add? Assuming your Perl is post-5.001,
105 execute a "perl -V" command and pay special attention to the "cc" and
106 "ccflags" information.
107
108 You'll have to choose the appropriate compiler (cc, gcc, et al.) for
109 your machine: "perl -MConfig -e 'print $Config{cc}'" will tell you what
110 to use.
111
112 You'll also have to choose the appropriate library directory
113 (/usr/local/lib/...) for your machine. If your compiler complains that
114 certain functions are undefined, or that it can't locate -lperl, then
115 you need to change the path following the "-L". If it complains that
116 it can't find EXTERN.h and perl.h, you need to change the path
117 following the "-I".
118
119 You may have to add extra libraries as well. Which ones? Perhaps
120 those printed by
121
122 perl -MConfig -e 'print $Config{libs}'
123
124 Provided your perl binary was properly configured and installed the
125 ExtUtils::Embed module will determine all of this information for you:
126
127 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
128
129 If the ExtUtils::Embed module isn't part of your Perl distribution, you
130 can retrieve it from
131 <http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/> (If this
132 documentation came from your Perl distribution, then you're running
133 5.004 or better and you already have it.)
134
135 The ExtUtils::Embed kit on CPAN also contains all source code for the
136 examples in this document, tests, additional examples and other
137 information you may find useful.
138
139 Adding a Perl interpreter to your C program
140 In a sense, perl (the C program) is a good example of embedding Perl
141 (the language), so I'll demonstrate embedding with miniperlmain.c,
142 included in the source distribution. Here's a bastardized, non-
143 portable version of miniperlmain.c containing the essentials of
144 embedding:
145
146 #include <EXTERN.h> /* from the Perl distribution */
147 #include <perl.h> /* from the Perl distribution */
148
149 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
150
151 int main(int argc, char **argv, char **env)
152 {
153 PERL_SYS_INIT3(&argc,&argv,&env);
154 my_perl = perl_alloc();
155 perl_construct(my_perl);
156 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
157 perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
158 perl_run(my_perl);
159 perl_destruct(my_perl);
160 perl_free(my_perl);
161 PERL_SYS_TERM();
162 }
163
164 Notice that we don't use the "env" pointer. Normally handed to
165 "perl_parse" as its final argument, "env" here is replaced by "NULL",
166 which means that the current environment will be used.
167
168 The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific
169 tune up of the C runtime environment necessary to run Perl
170 interpreters; they should only be called once regardless of how many
171 interpreters you create or destroy. Call PERL_SYS_INIT3() before you
172 create your first interpreter, and PERL_SYS_TERM() after you free your
173 last interpreter.
174
175 Since PERL_SYS_INIT3() may change "env", it may be more appropriate to
176 provide "env" as an argument to perl_parse().
177
178 Also notice that no matter what arguments you pass to perl_parse(),
179 PERL_SYS_INIT3() must be invoked on the C main() argc, argv and env and
180 only once.
181
182 Mind that argv[argc] must be NULL, same as those passed to a main
183 function in C.
184
185 Now compile this program (I'll call it interp.c) into an executable:
186
187 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
188
189 After a successful compilation, you'll be able to use interp just like
190 perl itself:
191
192 % interp
193 print "Pretty Good Perl \n";
194 print "10890 - 9801 is ", 10890 - 9801;
195 <CTRL-D>
196 Pretty Good Perl
197 10890 - 9801 is 1089
198
199 or
200
201 % interp -e 'printf("%x", 3735928559)'
202 deadbeef
203
204 You can also read and execute Perl statements from a file while in the
205 midst of your C program, by placing the filename in argv[1] before
206 calling perl_run.
207
208 Calling a Perl subroutine from your C program
209 To call individual Perl subroutines, you can use any of the call_*
210 functions documented in perlcall. In this example we'll use
211 "call_argv".
212
213 That's shown below, in a program I'll call showtime.c.
214
215 #include <EXTERN.h>
216 #include <perl.h>
217
218 static PerlInterpreter *my_perl;
219
220 int main(int argc, char **argv, char **env)
221 {
222 char *args[] = { NULL };
223 PERL_SYS_INIT3(&argc,&argv,&env);
224 my_perl = perl_alloc();
225 perl_construct(my_perl);
226
227 perl_parse(my_perl, NULL, argc, argv, NULL);
228 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
229
230 /*** skipping perl_run() ***/
231
232 call_argv("showtime", G_DISCARD | G_NOARGS, args);
233
234 perl_destruct(my_perl);
235 perl_free(my_perl);
236 PERL_SYS_TERM();
237 }
238
239 where showtime is a Perl subroutine that takes no arguments (that's the
240 G_NOARGS) and for which I'll ignore the return value (that's the
241 G_DISCARD). Those flags, and others, are discussed in perlcall.
242
243 I'll define the showtime subroutine in a file called showtime.pl:
244
245 print "I shan't be printed.";
246
247 sub showtime {
248 print time;
249 }
250
251 Simple enough. Now compile and run:
252
253 % cc -o showtime showtime.c \
254 `perl -MExtUtils::Embed -e ccopts -e ldopts`
255 % showtime showtime.pl
256 818284590
257
258 yielding the number of seconds that elapsed between January 1, 1970
259 (the beginning of the Unix epoch), and the moment I began writing this
260 sentence.
261
262 In this particular case we don't have to call perl_run, as we set the
263 PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
264 perl_destruct.
265
266 If you want to pass arguments to the Perl subroutine, you can add
267 strings to the "NULL"-terminated "args" list passed to call_argv. For
268 other data types, or to examine return values, you'll need to
269 manipulate the Perl stack. That's demonstrated in "Fiddling with the
270 Perl stack from your C program".
271
272 Evaluating a Perl statement from your C program
273 Perl provides two API functions to evaluate pieces of Perl code. These
274 are "eval_sv" in perlapi and "eval_pv" in perlapi.
275
276 Arguably, these are the only routines you'll ever need to execute
277 snippets of Perl code from within your C program. Your code can be as
278 long as you wish; it can contain multiple statements; it can employ
279 "use" in perlfunc, "require" in perlfunc, and "do" in perlfunc to
280 include external Perl files.
281
282 eval_pv lets us evaluate individual Perl strings, and then extract
283 variables for coercion into C types. The following program, string.c,
284 executes three Perl strings, extracting an "int" from the first, a
285 "float" from the second, and a "char *" from the third.
286
287 #include <EXTERN.h>
288 #include <perl.h>
289
290 static PerlInterpreter *my_perl;
291
292 main (int argc, char **argv, char **env)
293 {
294 char *embedding[] = { "", "-e", "0" };
295
296 PERL_SYS_INIT3(&argc,&argv,&env);
297 my_perl = perl_alloc();
298 perl_construct( my_perl );
299
300 perl_parse(my_perl, NULL, 3, embedding, NULL);
301 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
302 perl_run(my_perl);
303
304 /** Treat $a as an integer **/
305 eval_pv("$a = 3; $a **= 2", TRUE);
306 printf("a = %d\n", SvIV(get_sv("a", 0)));
307
308 /** Treat $a as a float **/
309 eval_pv("$a = 3.14; $a **= 2", TRUE);
310 printf("a = %f\n", SvNV(get_sv("a", 0)));
311
312 /** Treat $a as a string **/
313 eval_pv(
314 "$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
315 printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
316
317 perl_destruct(my_perl);
318 perl_free(my_perl);
319 PERL_SYS_TERM();
320 }
321
322 All of those strange functions with sv in their names help convert Perl
323 scalars to C types. They're described in perlguts and perlapi.
324
325 If you compile and run string.c, you'll see the results of using SvIV()
326 to create an "int", SvNV() to create a "float", and SvPV() to create a
327 string:
328
329 a = 9
330 a = 9.859600
331 a = Just Another Perl Hacker
332
333 In the example above, we've created a global variable to temporarily
334 store the computed value of our eval'ed expression. It is also
335 possible and in most cases a better strategy to fetch the return value
336 from eval_pv() instead. Example:
337
338 ...
339 SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
340 printf("%s\n", SvPV_nolen(val));
341 ...
342
343 This way, we avoid namespace pollution by not creating global variables
344 and we've simplified our code as well.
345
346 Performing Perl pattern matches and substitutions from your C program
347 The eval_sv() function lets us evaluate strings of Perl code, so we can
348 define some functions that use it to "specialize" in matches and
349 substitutions: match(), substitute(), and matches().
350
351 I32 match(SV *string, char *pattern);
352
353 Given a string and a pattern (e.g., "m/clasp/" or "/\b\w*\b/", which in
354 your C program might appear as "/\\b\\w*\\b/"), match() returns 1 if
355 the string matches the pattern and 0 otherwise.
356
357 int substitute(SV **string, char *pattern);
358
359 Given a pointer to an "SV" and an "=~" operation (e.g.,
360 "s/bob/robert/g" or "tr[A-Z][a-z]"), substitute() modifies the string
361 within the "SV" as according to the operation, returning the number of
362 substitutions made.
363
364 SSize_t matches(SV *string, char *pattern, AV **matches);
365
366 Given an "SV", a pattern, and a pointer to an empty "AV", matches()
367 evaluates "$string =~ $pattern" in a list context, and fills in matches
368 with the array elements, returning the number of matches found.
369
370 Here's a sample program, match.c, that uses all three (long lines have
371 been wrapped here):
372
373 #include <EXTERN.h>
374 #include <perl.h>
375
376 static PerlInterpreter *my_perl;
377
378 /** my_eval_sv(code, error_check)
379 ** kinda like eval_sv(),
380 ** but we pop the return value off the stack
381 **/
382 SV* my_eval_sv(SV *sv, I32 croak_on_error)
383 {
384 dSP;
385 SV* retval;
386
387
388 PUSHMARK(SP);
389 eval_sv(sv, G_SCALAR);
390
391 SPAGAIN;
392 retval = POPs;
393 PUTBACK;
394
395 if (croak_on_error && SvTRUE(ERRSV))
396 croak(SvPVx_nolen(ERRSV));
397
398 return retval;
399 }
400
401 /** match(string, pattern)
402 **
403 ** Used for matches in a scalar context.
404 **
405 ** Returns 1 if the match was successful; 0 otherwise.
406 **/
407
408 I32 match(SV *string, char *pattern)
409 {
410 SV *command = newSV(0), *retval;
411
412 sv_setpvf(command, "my $string = '%s'; $string =~ %s",
413 SvPV_nolen(string), pattern);
414
415 retval = my_eval_sv(command, TRUE);
416 SvREFCNT_dec(command);
417
418 return SvIV(retval);
419 }
420
421 /** substitute(string, pattern)
422 **
423 ** Used for =~ operations that
424 ** modify their left-hand side (s/// and tr///)
425 **
426 ** Returns the number of successful matches, and
427 ** modifies the input string if there were any.
428 **/
429
430 I32 substitute(SV **string, char *pattern)
431 {
432 SV *command = newSV(0), *retval;
433
434 sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
435 SvPV_nolen(*string), pattern);
436
437 retval = my_eval_sv(command, TRUE);
438 SvREFCNT_dec(command);
439
440 *string = get_sv("string", 0);
441 return SvIV(retval);
442 }
443
444 /** matches(string, pattern, matches)
445 **
446 ** Used for matches in a list context.
447 **
448 ** Returns the number of matches,
449 ** and fills in **matches with the matching substrings
450 **/
451
452 SSize_t matches(SV *string, char *pattern, AV **match_list)
453 {
454 SV *command = newSV(0);
455 SSize_t num_matches;
456
457 sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
458 SvPV_nolen(string), pattern);
459
460 my_eval_sv(command, TRUE);
461 SvREFCNT_dec(command);
462
463 *match_list = get_av("array", 0);
464 num_matches = av_top_index(*match_list) + 1;
465
466 return num_matches;
467 }
468
469 main (int argc, char **argv, char **env)
470 {
471 char *embedding[] = { "", "-e", "0" };
472 AV *match_list;
473 I32 num_matches, i;
474 SV *text;
475
476 PERL_SYS_INIT3(&argc,&argv,&env);
477 my_perl = perl_alloc();
478 perl_construct(my_perl);
479 perl_parse(my_perl, NULL, 3, embedding, NULL);
480 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
481
482 text = newSV(0);
483 sv_setpv(text, "When he is at a convenience store and the "
484 "bill comes to some amount like 76 cents, Maynard is "
485 "aware that there is something he *should* do, something "
486 "that will enable him to get back a quarter, but he has "
487 "no idea *what*. He fumbles through his red squeezey "
488 "changepurse and gives the boy three extra pennies with "
489 "his dollar, hoping that he might luck into the correct "
490 "amount. The boy gives him back two of his own pennies "
491 "and then the big shiny quarter that is his prize. "
492 "-RICHH");
493
494 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
495 printf("match: Text contains the word 'quarter'.\n\n");
496 else
497 printf("match: Text doesn't contain the word 'quarter'.\n\n");
498
499 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
500 printf("match: Text contains the word 'eighth'.\n\n");
501 else
502 printf("match: Text doesn't contain the word 'eighth'.\n\n");
503
504 /** Match all occurrences of /wi../ **/
505 num_matches = matches(text, "m/(wi..)/g", &match_list);
506 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
507
508 for (i = 0; i < num_matches; i++)
509 printf("match: %s\n",
510 SvPV_nolen(*av_fetch(match_list, i, FALSE)));
511 printf("\n");
512
513 /** Remove all vowels from text **/
514 num_matches = substitute(&text, "s/[aeiou]//gi");
515 if (num_matches) {
516 printf("substitute: s/[aeiou]//gi...%lu substitutions made.\n",
517 (unsigned long)num_matches);
518 printf("Now text is: %s\n\n", SvPV_nolen(text));
519 }
520
521 /** Attempt a substitution **/
522 if (!substitute(&text, "s/Perl/C/")) {
523 printf("substitute: s/Perl/C...No substitution made.\n\n");
524 }
525
526 SvREFCNT_dec(text);
527 PL_perl_destruct_level = 1;
528 perl_destruct(my_perl);
529 perl_free(my_perl);
530 PERL_SYS_TERM();
531 }
532
533 which produces the output (again, long lines have been wrapped here)
534
535 match: Text contains the word 'quarter'.
536
537 match: Text doesn't contain the word 'eighth'.
538
539 matches: m/(wi..)/g found 2 matches...
540 match: will
541 match: with
542
543 substitute: s/[aeiou]//gi...139 substitutions made.
544 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
545 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt
546 bck qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd
547 gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct
548 mnt. Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s
549 hs prz. -RCHH
550
551 substitute: s/Perl/C...No substitution made.
552
553 Fiddling with the Perl stack from your C program
554 When trying to explain stacks, most computer science textbooks mumble
555 something about spring-loaded columns of cafeteria plates: the last
556 thing you pushed on the stack is the first thing you pop off. That'll
557 do for our purposes: your C program will push some arguments onto "the
558 Perl stack", shut its eyes while some magic happens, and then pop the
559 results--the return value of your Perl subroutine--off the stack.
560
561 First you'll need to know how to convert between C types and Perl
562 types, with newSViv() and sv_setnv() and newAV() and all their friends.
563 They're described in perlguts and perlapi.
564
565 Then you'll need to know how to manipulate the Perl stack. That's
566 described in perlcall.
567
568 Once you've understood those, embedding Perl in C is easy.
569
570 Because C has no builtin function for integer exponentiation, let's
571 make Perl's ** operator available to it (this is less useful than it
572 sounds, because Perl implements ** with C's pow() function). First
573 I'll create a stub exponentiation function in power.pl:
574
575 sub expo {
576 my ($a, $b) = @_;
577 return $a ** $b;
578 }
579
580 Now I'll create a C program, power.c, with a function PerlPower() that
581 contains all the perlguts necessary to push the two arguments into
582 expo() and to pop the return value out. Take a deep breath...
583
584 #include <EXTERN.h>
585 #include <perl.h>
586
587 static PerlInterpreter *my_perl;
588
589 static void
590 PerlPower(int a, int b)
591 {
592 dSP; /* initialize stack pointer */
593 ENTER; /* everything created after here */
594 SAVETMPS; /* ...is a temporary variable. */
595 PUSHMARK(SP); /* remember the stack pointer */
596 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
597 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
598 PUTBACK; /* make local stack pointer global */
599 call_pv("expo", G_SCALAR); /* call the function */
600 SPAGAIN; /* refresh stack pointer */
601 /* pop the return value from stack */
602 printf ("%d to the %dth power is %d.\n", a, b, POPi);
603 PUTBACK;
604 FREETMPS; /* free that return value */
605 LEAVE; /* ...and the XPUSHed "mortal" args.*/
606 }
607
608 int main (int argc, char **argv, char **env)
609 {
610 char *my_argv[] = { "", "power.pl" };
611
612 PERL_SYS_INIT3(&argc,&argv,&env);
613 my_perl = perl_alloc();
614 perl_construct( my_perl );
615
616 perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
617 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
618 perl_run(my_perl);
619
620 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
621
622 perl_destruct(my_perl);
623 perl_free(my_perl);
624 PERL_SYS_TERM();
625 }
626
627 Compile and run:
628
629 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
630
631 % power
632 3 to the 4th power is 81.
633
634 Maintaining a persistent interpreter
635 When developing interactive and/or potentially long-running
636 applications, it's a good idea to maintain a persistent interpreter
637 rather than allocating and constructing a new interpreter multiple
638 times. The major reason is speed: since Perl will only be loaded into
639 memory once.
640
641 However, you have to be more cautious with namespace and variable
642 scoping when using a persistent interpreter. In previous examples
643 we've been using global variables in the default package "main". We
644 knew exactly what code would be run, and assumed we could avoid
645 variable collisions and outrageous symbol table growth.
646
647 Let's say your application is a server that will occasionally run Perl
648 code from some arbitrary file. Your server has no way of knowing what
649 code it's going to run. Very dangerous.
650
651 If the file is pulled in by "perl_parse()", compiled into a newly
652 constructed interpreter, and subsequently cleaned out with
653 "perl_destruct()" afterwards, you're shielded from most namespace
654 troubles.
655
656 One way to avoid namespace collisions in this scenario is to translate
657 the filename into a guaranteed-unique package name, and then compile
658 the code into that package using "eval" in perlfunc. In the example
659 below, each file will only be compiled once. Or, the application might
660 choose to clean out the symbol table associated with the file after
661 it's no longer needed. Using "call_argv" in perlapi, We'll call the
662 subroutine "Embed::Persistent::eval_file" which lives in the file
663 "persistent.pl" and pass the filename and boolean cleanup/cache flag as
664 arguments.
665
666 Note that the process will continue to grow for each file that it uses.
667 In addition, there might be "AUTOLOAD"ed subroutines and other
668 conditions that cause Perl's symbol table to grow. You might want to
669 add some logic that keeps track of the process size, or restarts itself
670 after a certain number of requests, to ensure that memory consumption
671 is minimized. You'll also want to scope your variables with "my" in
672 perlfunc whenever possible.
673
674 package Embed::Persistent;
675 #persistent.pl
676
677 use strict;
678 our %Cache;
679 use Symbol qw(delete_package);
680
681 sub valid_package_name {
682 my($string) = @_;
683 $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
684 # second pass only for words starting with a digit
685 $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
686
687 # Dress it up as a real package name
688 $string =~ s|/|::|g;
689 return "Embed" . $string;
690 }
691
692 sub eval_file {
693 my($filename, $delete) = @_;
694 my $package = valid_package_name($filename);
695 my $mtime = -M $filename;
696 if(defined $Cache{$package}{mtime}
697 &&
698 $Cache{$package}{mtime} <= $mtime)
699 {
700 # we have compiled this subroutine already,
701 # it has not been updated on disk, nothing left to do
702 print STDERR "already compiled $package->handler\n";
703 }
704 else {
705 local *FH;
706 open FH, $filename or die "open '$filename' $!";
707 local($/) = undef;
708 my $sub = <FH>;
709 close FH;
710
711 #wrap the code into a subroutine inside our unique package
712 my $eval = qq{package $package; sub handler { $sub; }};
713 {
714 # hide our variables within this block
715 my($filename,$mtime,$package,$sub);
716 eval $eval;
717 }
718 die $@ if $@;
719
720 #cache it unless we're cleaning out each time
721 $Cache{$package}{mtime} = $mtime unless $delete;
722 }
723
724 eval {$package->handler;};
725 die $@ if $@;
726
727 delete_package($package) if $delete;
728
729 #take a look if you want
730 #print Devel::Symdump->rnew($package)->as_string, $/;
731 }
732
733 1;
734
735 __END__
736
737 /* persistent.c */
738 #include <EXTERN.h>
739 #include <perl.h>
740
741 /* 1 = clean out filename's symbol table after each request,
742 0 = don't
743 */
744 #ifndef DO_CLEAN
745 #define DO_CLEAN 0
746 #endif
747
748 #define BUFFER_SIZE 1024
749
750 static PerlInterpreter *my_perl = NULL;
751
752 int
753 main(int argc, char **argv, char **env)
754 {
755 char *embedding[] = { "", "persistent.pl" };
756 char *args[] = { "", DO_CLEAN, NULL };
757 char filename[BUFFER_SIZE];
758 int exitstatus = 0;
759
760 PERL_SYS_INIT3(&argc,&argv,&env);
761 if((my_perl = perl_alloc()) == NULL) {
762 fprintf(stderr, "no memory!");
763 exit(1);
764 }
765 perl_construct(my_perl);
766
767 PL_origalen = 1; /* don't let $0 assignment update the
768 proctitle or embedding[0] */
769 exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
770 PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
771 if(!exitstatus) {
772 exitstatus = perl_run(my_perl);
773
774 while(printf("Enter file name: ") &&
775 fgets(filename, BUFFER_SIZE, stdin)) {
776
777 filename[strlen(filename)-1] = '\0'; /* strip \n */
778 /* call the subroutine,
779 passing it the filename as an argument */
780 args[0] = filename;
781 call_argv("Embed::Persistent::eval_file",
782 G_DISCARD | G_EVAL, args);
783
784 /* check $@ */
785 if(SvTRUE(ERRSV))
786 fprintf(stderr, "eval error: %s\n", SvPV_nolen(ERRSV));
787 }
788 }
789
790 PL_perl_destruct_level = 0;
791 perl_destruct(my_perl);
792 perl_free(my_perl);
793 PERL_SYS_TERM();
794 exit(exitstatus);
795 }
796
797 Now compile:
798
799 % cc -o persistent persistent.c \
800 `perl -MExtUtils::Embed -e ccopts -e ldopts`
801
802 Here's an example script file:
803
804 #test.pl
805 my $string = "hello";
806 foo($string);
807
808 sub foo {
809 print "foo says: @_\n";
810 }
811
812 Now run:
813
814 % persistent
815 Enter file name: test.pl
816 foo says: hello
817 Enter file name: test.pl
818 already compiled Embed::test_2epl->handler
819 foo says: hello
820 Enter file name: ^C
821
822 Execution of END blocks
823 Traditionally END blocks have been executed at the end of the perl_run.
824 This causes problems for applications that never call perl_run. Since
825 perl 5.7.2 you can specify "PL_exit_flags |= PERL_EXIT_DESTRUCT_END" to
826 get the new behaviour. This also enables the running of END blocks if
827 the perl_parse fails and "perl_destruct" will return the exit value.
828
829 $0 assignments
830 When a perl script assigns a value to $0 then the perl runtime will try
831 to make this value show up as the program name reported by "ps" by
832 updating the memory pointed to by the argv passed to perl_parse() and
833 also calling API functions like setproctitle() where available. This
834 behaviour might not be appropriate when embedding perl and can be
835 disabled by assigning the value 1 to the variable "PL_origalen" before
836 perl_parse() is called.
837
838 The persistent.c example above is for instance likely to segfault when
839 $0 is assigned to if the "PL_origalen = 1;" assignment is removed.
840 This because perl will try to write to the read only memory of the
841 "embedding[]" strings.
842
843 Maintaining multiple interpreter instances
844 Some rare applications will need to create more than one interpreter
845 during a session. Such an application might sporadically decide to
846 release any resources associated with the interpreter.
847
848 The program must take care to ensure that this takes place before the
849 next interpreter is constructed. By default, when perl is not built
850 with any special options, the global variable "PL_perl_destruct_level"
851 is set to 0, since extra cleaning isn't usually needed when a program
852 only ever creates a single interpreter in its entire lifetime.
853
854 Setting "PL_perl_destruct_level" to 1 makes everything squeaky clean:
855
856 while(1) {
857 ...
858 /* reset global variables here with PL_perl_destruct_level = 1 */
859 PL_perl_destruct_level = 1;
860 perl_construct(my_perl);
861 ...
862 /* clean and reset _everything_ during perl_destruct */
863 PL_perl_destruct_level = 1;
864 perl_destruct(my_perl);
865 perl_free(my_perl);
866 ...
867 /* let's go do it again! */
868 }
869
870 When perl_destruct() is called, the interpreter's syntax parse tree and
871 symbol tables are cleaned up, and global variables are reset. The
872 second assignment to "PL_perl_destruct_level" is needed because
873 perl_construct resets it to 0.
874
875 Now suppose we have more than one interpreter instance running at the
876 same time. This is feasible, but only if you used the Configure option
877 "-Dusemultiplicity" or the options "-Dusethreads -Duseithreads" when
878 building perl. By default, enabling one of these Configure options
879 sets the per-interpreter global variable "PL_perl_destruct_level" to 1,
880 so that thorough cleaning is automatic and interpreter variables are
881 initialized correctly. Even if you don't intend to run two or more
882 interpreters at the same time, but to run them sequentially, like in
883 the above example, it is recommended to build perl with the
884 "-Dusemultiplicity" option otherwise some interpreter variables may not
885 be initialized correctly between consecutive runs and your application
886 may crash.
887
888 See also "Thread-aware system interfaces" in perlxs.
889
890 Using "-Dusethreads -Duseithreads" rather than "-Dusemultiplicity" is
891 more appropriate if you intend to run multiple interpreters
892 concurrently in different threads, because it enables support for
893 linking in the thread libraries of your system with the interpreter.
894
895 Let's give it a try:
896
897 #include <EXTERN.h>
898 #include <perl.h>
899
900 /* we're going to embed two interpreters */
901
902 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
903
904 int main(int argc, char **argv, char **env)
905 {
906 PerlInterpreter *one_perl, *two_perl;
907 char *one_args[] = { "one_perl", SAY_HELLO };
908 char *two_args[] = { "two_perl", SAY_HELLO };
909
910 PERL_SYS_INIT3(&argc,&argv,&env);
911 one_perl = perl_alloc();
912 two_perl = perl_alloc();
913
914 PERL_SET_CONTEXT(one_perl);
915 perl_construct(one_perl);
916 PERL_SET_CONTEXT(two_perl);
917 perl_construct(two_perl);
918
919 PERL_SET_CONTEXT(one_perl);
920 perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
921 PERL_SET_CONTEXT(two_perl);
922 perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
923
924 PERL_SET_CONTEXT(one_perl);
925 perl_run(one_perl);
926 PERL_SET_CONTEXT(two_perl);
927 perl_run(two_perl);
928
929 PERL_SET_CONTEXT(one_perl);
930 perl_destruct(one_perl);
931 PERL_SET_CONTEXT(two_perl);
932 perl_destruct(two_perl);
933
934 PERL_SET_CONTEXT(one_perl);
935 perl_free(one_perl);
936 PERL_SET_CONTEXT(two_perl);
937 perl_free(two_perl);
938 PERL_SYS_TERM();
939 }
940
941 Note the calls to PERL_SET_CONTEXT(). These are necessary to
942 initialize the global state that tracks which interpreter is the
943 "current" one on the particular process or thread that may be running
944 it. It should always be used if you have more than one interpreter and
945 are making perl API calls on both interpreters in an interleaved
946 fashion.
947
948 PERL_SET_CONTEXT(interp) should also be called whenever "interp" is
949 used by a thread that did not create it (using either perl_alloc(), or
950 the more esoteric perl_clone()).
951
952 Compile as usual:
953
954 % cc -o multiplicity multiplicity.c \
955 `perl -MExtUtils::Embed -e ccopts -e ldopts`
956
957 Run it, Run it:
958
959 % multiplicity
960 Hi, I'm one_perl
961 Hi, I'm two_perl
962
963 Using Perl modules, which themselves use C libraries, from your C program
964 If you've played with the examples above and tried to embed a script
965 that use()s a Perl module (such as Socket) which itself uses a C or C++
966 library, this probably happened:
967
968 Can't load module Socket, dynamic loading not available in this perl.
969 (You may need to build a new perl executable which either supports
970 dynamic loading or has the Socket module statically linked into it.)
971
972 What's wrong?
973
974 Your interpreter doesn't know how to communicate with these extensions
975 on its own. A little glue will help. Up until now you've been calling
976 perl_parse(), handing it NULL for the second argument:
977
978 perl_parse(my_perl, NULL, argc, my_argv, NULL);
979
980 That's where the glue code can be inserted to create the initial
981 contact between Perl and linked C/C++ routines. Let's take a look some
982 pieces of perlmain.c to see how Perl does this:
983
984 static void xs_init (pTHX);
985
986 EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
987 EXTERN_C void boot_Socket (pTHX_ CV* cv);
988
989
990 EXTERN_C void
991 xs_init(pTHX)
992 {
993 char *file = __FILE__;
994 /* DynaLoader is a special case */
995 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
996 newXS("Socket::bootstrap", boot_Socket, file);
997 }
998
999 Simply put: for each extension linked with your Perl executable
1000 (determined during its initial configuration on your computer or when
1001 adding a new extension), a Perl subroutine is created to incorporate
1002 the extension's routines. Normally, that subroutine is named
1003 Module::bootstrap() and is invoked when you say use Module. In turn,
1004 this hooks into an XSUB, boot_Module, which creates a Perl counterpart
1005 for each of the extension's XSUBs. Don't worry about this part; leave
1006 that to the xsubpp and extension authors. If your extension is
1007 dynamically loaded, DynaLoader creates Module::bootstrap() for you on
1008 the fly. In fact, if you have a working DynaLoader then there is
1009 rarely any need to link in any other extensions statically.
1010
1011 Once you have this code, slap it into the second argument of
1012 perl_parse():
1013
1014 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
1015
1016 Then compile:
1017
1018 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
1019
1020 % interp
1021 use Socket;
1022 use SomeDynamicallyLoadedModule;
1023
1024 print "Now I can use extensions!\n"'
1025
1026 ExtUtils::Embed can also automate writing the xs_init glue code.
1027
1028 % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
1029 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
1030 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
1031 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
1032
1033 Consult perlxs, perlguts, and perlapi for more details.
1034
1035 Using embedded Perl with POSIX locales
1036 (See perllocale for information about these.) When a Perl interpreter
1037 normally starts up, it tells the system it wants to use the system's
1038 default locale. This is often, but not necessarily, the "C" or "POSIX"
1039 locale. Absent a "use locale" within the perl code, this mostly has no
1040 effect (but see "Not within the scope of "use locale"" in perllocale).
1041 Also, there is not a problem if the locale you want to use in your
1042 embedded Perl is the same as the system default. However, this doesn't
1043 work if you have set up and want to use a locale that isn't the system
1044 default one. Starting in Perl v5.20, you can tell the embedded Perl
1045 interpreter that the locale is already properly set up, and to skip
1046 doing its own normal initialization. It skips if the environment
1047 variable "PERL_SKIP_LOCALE_INIT" is set (even if set to 0 or ""). A
1048 Perl that has this capability will define the C pre-processor symbol
1049 "HAS_SKIP_LOCALE_INIT". This allows code that has to work with
1050 multiple Perl versions to do some sort of work-around when confronted
1051 with an earlier Perl.
1052
1054 If you completely hide the short forms of the Perl public API, add
1055 -DPERL_NO_SHORT_NAMES to the compilation flags. This means that for
1056 example instead of writing
1057
1058 warn("%d bottles of beer on the wall", bottlecount);
1059
1060 you will have to write the explicit full form
1061
1062 Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
1063
1064 (See "Background and PERL_IMPLICIT_CONTEXT" in perlguts for the
1065 explanation of the "aTHX_". ) Hiding the short forms is very useful
1066 for avoiding all sorts of nasty (C preprocessor or otherwise) conflicts
1067 with other software packages (Perl defines about 2400 APIs with these
1068 short names, take or leave few hundred, so there certainly is room for
1069 conflict.)
1070
1072 You can sometimes write faster code in C, but you can always write code
1073 faster in Perl. Because you can use each from the other, combine them
1074 as you wish.
1075
1077 Jon Orwant <orwant@media.mit.edu> and Doug MacEachern
1078 <dougm@covalent.net>, with small contributions from Tim Bunce, Tom
1079 Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
1080 Zakharevich.
1081
1082 Doug MacEachern has an article on embedding in Volume 1, Issue 4 of The
1083 Perl Journal ( <http://www.tpj.com/> ). Doug is also the developer of
1084 the most widely-used Perl embedding: the mod_perl system
1085 (perl.apache.org), which embeds Perl in the Apache web server. Oracle,
1086 Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl have used
1087 this model for Oracle, Netscape and Internet Information Server Perl
1088 plugins.
1089
1091 Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant.
1092 All Rights Reserved.
1093
1094 This document may be distributed under the same terms as Perl itself.
1095
1096
1097
1098perl v5.26.3 2018-03-23 PERLEMBED(1)