1PERLEMBED(1)           Perl Programmers Reference Guide           PERLEMBED(1)
2
3
4

NAME

6       perlembed - how to embed perl in your C program
7

DESCRIPTION

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 -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 <https://metacpan.org/pod/ExtUtils::Embed> (If
131       this documentation came from your Perl distribution, then you're
132       running 5.004 or better and you already have it.)
133
134       The ExtUtils::Embed kit on CPAN also contains all source code for the
135       examples in this document, tests, additional examples and other
136       information you may find useful.
137
138   Adding a Perl interpreter to your C program
139       In a sense, perl (the C program) is a good example of embedding Perl
140       (the language), so I'll demonstrate embedding with miniperlmain.c,
141       included in the source distribution.  Here's a bastardized, non-
142       portable version of miniperlmain.c containing the essentials of
143       embedding:
144
145        #include <EXTERN.h>               /* from the Perl distribution     */
146        #include <perl.h>                 /* from the Perl distribution     */
147
148        static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/
149
150        int main(int argc, char **argv, char **env)
151        {
152               PERL_SYS_INIT3(&argc,&argv,&env);
153               my_perl = perl_alloc();
154               perl_construct(my_perl);
155               PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
156               perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
157               perl_run(my_perl);
158               perl_destruct(my_perl);
159               perl_free(my_perl);
160               PERL_SYS_TERM();
161               exit(EXIT_SUCCESS);
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               exit(EXIT_SUCCESS);
238           }
239
240       where showtime is a Perl subroutine that takes no arguments (that's the
241       G_NOARGS) and for which I'll ignore the return value (that's the
242       G_DISCARD).  Those flags, and others, are discussed in perlcall.
243
244       I'll define the showtime subroutine in a file called showtime.pl:
245
246        print "I shan't be printed.";
247
248        sub showtime {
249            print time;
250        }
251
252       Simple enough. Now compile and run:
253
254        % cc -o showtime showtime.c \
255            `perl -MExtUtils::Embed -e ccopts -e ldopts`
256        % showtime showtime.pl
257        818284590
258
259       yielding the number of seconds that elapsed between January 1, 1970
260       (the beginning of the Unix epoch), and the moment I began writing this
261       sentence.
262
263       In this particular case we don't have to call perl_run, as we set the
264       PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
265       perl_destruct.
266
267       If you want to pass arguments to the Perl subroutine, you can add
268       strings to the "NULL"-terminated "args" list passed to call_argv.  For
269       other data types, or to examine return values, you'll need to
270       manipulate the Perl stack.  That's demonstrated in "Fiddling with the
271       Perl stack from your C program".
272
273   Evaluating a Perl statement from your C program
274       Perl provides two API functions to evaluate pieces of Perl code.  These
275       are "eval_sv" in perlapi and "eval_pv" in perlapi.
276
277       Arguably, these are the only routines you'll ever need to execute
278       snippets of Perl code from within your C program.  Your code can be as
279       long as you wish; it can contain multiple statements; it can employ
280       "use" in perlfunc, "require" in perlfunc, and "do" in perlfunc to
281       include external Perl files.
282
283       eval_pv lets us evaluate individual Perl strings, and then extract
284       variables for coercion into C types.  The following program, string.c,
285       executes three Perl strings, extracting an "int" from the first, a
286       "float" from the second, and a "char *" from the third.
287
288        #include <EXTERN.h>
289        #include <perl.h>
290
291        static PerlInterpreter *my_perl;
292
293        main (int argc, char **argv, char **env)
294        {
295            char *embedding[] = { "", "-e", "0", NULL };
296
297            PERL_SYS_INIT3(&argc,&argv,&env);
298            my_perl = perl_alloc();
299            perl_construct( my_perl );
300
301            perl_parse(my_perl, NULL, 3, embedding, NULL);
302            PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
303            perl_run(my_perl);
304
305            /** Treat $a as an integer **/
306            eval_pv("$a = 3; $a **= 2", TRUE);
307            printf("a = %d\n", SvIV(get_sv("a", 0)));
308
309            /** Treat $a as a float **/
310            eval_pv("$a = 3.14; $a **= 2", TRUE);
311            printf("a = %f\n", SvNV(get_sv("a", 0)));
312
313            /** Treat $a as a string **/
314            eval_pv(
315              "$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
316            printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
317
318            perl_destruct(my_perl);
319            perl_free(my_perl);
320            PERL_SYS_TERM();
321        }
322
323       All of those strange functions with sv in their names help convert Perl
324       scalars to C types.  They're described in perlguts and perlapi.
325
326       If you compile and run string.c, you'll see the results of using SvIV()
327       to create an "int", SvNV() to create a "float", and SvPV() to create a
328       string:
329
330          a = 9
331          a = 9.859600
332          a = Just Another Perl Hacker
333
334       In the example above, we've created a global variable to temporarily
335       store the computed value of our eval'ed expression.  It is also
336       possible and in most cases a better strategy to fetch the return value
337       from eval_pv() instead.  Example:
338
339          ...
340          SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
341          printf("%s\n", SvPV_nolen(val));
342          ...
343
344       This way, we avoid namespace pollution by not creating global variables
345       and we've simplified our code as well.
346
347   Performing Perl pattern matches and substitutions from your C program
348       The eval_sv() function lets us evaluate strings of Perl code, so we can
349       define some functions that use it to "specialize" in matches and
350       substitutions: match(), substitute(), and matches().
351
352          I32 match(SV *string, char *pattern);
353
354       Given a string and a pattern (e.g., "m/clasp/" or "/\b\w*\b/", which in
355       your C program might appear as "/\\b\\w*\\b/"), match() returns 1 if
356       the string matches the pattern and 0 otherwise.
357
358          int substitute(SV **string, char *pattern);
359
360       Given a pointer to an "SV" and an "=~" operation (e.g.,
361       "s/bob/robert/g" or "tr[A-Z][a-z]"), substitute() modifies the string
362       within the "SV" as according to the operation, returning the number of
363       substitutions made.
364
365          SSize_t matches(SV *string, char *pattern, AV **matches);
366
367       Given an "SV", a pattern, and a pointer to an empty "AV", matches()
368       evaluates "$string =~ $pattern" in a list context, and fills in matches
369       with the array elements, returning the number of matches found.
370
371       Here's a sample program, match.c, that uses all three (long lines have
372       been wrapped here):
373
374        #include <EXTERN.h>
375        #include <perl.h>
376
377        static PerlInterpreter *my_perl;
378
379        /** my_eval_sv(code, error_check)
380        ** kinda like eval_sv(),
381        ** but we pop the return value off the stack
382        **/
383        SV* my_eval_sv(SV *sv, I32 croak_on_error)
384        {
385            dSP;
386            SV* retval;
387
388
389            PUSHMARK(SP);
390            eval_sv(sv, G_SCALAR);
391
392            SPAGAIN;
393            retval = POPs;
394            PUTBACK;
395
396            if (croak_on_error && SvTRUE(ERRSV))
397               croak_sv(ERRSV);
398
399            return retval;
400        }
401
402        /** match(string, pattern)
403        **
404        ** Used for matches in a scalar context.
405        **
406        ** Returns 1 if the match was successful; 0 otherwise.
407        **/
408
409        I32 match(SV *string, char *pattern)
410        {
411            SV *command = newSV(0), *retval;
412
413            sv_setpvf(command, "my $string = '%s'; $string =~ %s",
414                     SvPV_nolen(string), pattern);
415
416            retval = my_eval_sv(command, TRUE);
417            SvREFCNT_dec(command);
418
419            return SvIV(retval);
420        }
421
422        /** substitute(string, pattern)
423        **
424        ** Used for =~ operations that
425        ** modify their left-hand side (s/// and tr///)
426        **
427        ** Returns the number of successful matches, and
428        ** modifies the input string if there were any.
429        **/
430
431        I32 substitute(SV **string, char *pattern)
432        {
433            SV *command = newSV(0), *retval;
434
435            sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
436                     SvPV_nolen(*string), pattern);
437
438            retval = my_eval_sv(command, TRUE);
439            SvREFCNT_dec(command);
440
441            *string = get_sv("string", 0);
442            return SvIV(retval);
443        }
444
445        /** matches(string, pattern, matches)
446        **
447        ** Used for matches in a list context.
448        **
449        ** Returns the number of matches,
450        ** and fills in **matches with the matching substrings
451        **/
452
453        SSize_t matches(SV *string, char *pattern, AV **match_list)
454        {
455            SV *command = newSV(0);
456            SSize_t num_matches;
457
458            sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
459                     SvPV_nolen(string), pattern);
460
461            my_eval_sv(command, TRUE);
462            SvREFCNT_dec(command);
463
464            *match_list = get_av("array", 0);
465            num_matches = av_top_index(*match_list) + 1;
466
467            return num_matches;
468        }
469
470        main (int argc, char **argv, char **env)
471        {
472            char *embedding[] = { "", "-e", "0", NULL };
473            AV *match_list;
474            I32 num_matches, i;
475            SV *text;
476
477            PERL_SYS_INIT3(&argc,&argv,&env);
478            my_perl = perl_alloc();
479            perl_construct(my_perl);
480            perl_parse(my_perl, NULL, 3, embedding, NULL);
481            PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
482
483            text = newSV(0);
484            sv_setpv(text, "When he is at a convenience store and the "
485               "bill comes to some amount like 76 cents, Maynard is "
486               "aware that there is something he *should* do, something "
487               "that will enable him to get back a quarter, but he has "
488               "no idea *what*.  He fumbles through his red squeezey "
489               "changepurse and gives the boy three extra pennies with "
490               "his dollar, hoping that he might luck into the correct "
491               "amount.  The boy gives him back two of his own pennies "
492               "and then the big shiny quarter that is his prize. "
493               "-RICHH");
494
495            if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
496               printf("match: Text contains the word 'quarter'.\n\n");
497            else
498               printf("match: Text doesn't contain the word 'quarter'.\n\n");
499
500            if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
501               printf("match: Text contains the word 'eighth'.\n\n");
502            else
503               printf("match: Text doesn't contain the word 'eighth'.\n\n");
504
505            /** Match all occurrences of /wi../ **/
506            num_matches = matches(text, "m/(wi..)/g", &match_list);
507            printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
508
509            for (i = 0; i < num_matches; i++)
510                printf("match: %s\n",
511                         SvPV_nolen(*av_fetch(match_list, i, FALSE)));
512            printf("\n");
513
514            /** Remove all vowels from text **/
515            num_matches = substitute(&text, "s/[aeiou]//gi");
516            if (num_matches) {
517               printf("substitute: s/[aeiou]//gi...%lu substitutions made.\n",
518                      (unsigned long)num_matches);
519               printf("Now text is: %s\n\n", SvPV_nolen(text));
520            }
521
522            /** Attempt a substitution **/
523            if (!substitute(&text, "s/Perl/C/")) {
524               printf("substitute: s/Perl/C...No substitution made.\n\n");
525            }
526
527            SvREFCNT_dec(text);
528            PL_perl_destruct_level = 1;
529            perl_destruct(my_perl);
530            perl_free(my_perl);
531            PERL_SYS_TERM();
532        }
533
534       which produces the output (again, long lines have been wrapped here)
535
536         match: Text contains the word 'quarter'.
537
538         match: Text doesn't contain the word 'eighth'.
539
540         matches: m/(wi..)/g found 2 matches...
541         match: will
542         match: with
543
544         substitute: s/[aeiou]//gi...139 substitutions made.
545         Now text is: Whn h s t  cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
546         Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt
547         bck qrtr, bt h hs n d *wht*.  H fmbls thrgh hs rd sqzy chngprs nd
548         gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct
549         mnt.  Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s
550         hs prz. -RCHH
551
552         substitute: s/Perl/C...No substitution made.
553
554   Fiddling with the Perl stack from your C program
555       When trying to explain stacks, most computer science textbooks mumble
556       something about spring-loaded columns of cafeteria plates: the last
557       thing you pushed on the stack is the first thing you pop off.  That'll
558       do for our purposes: your C program will push some arguments onto "the
559       Perl stack", shut its eyes while some magic happens, and then pop the
560       results--the return value of your Perl subroutine--off the stack.
561
562       First you'll need to know how to convert between C types and Perl
563       types, with newSViv() and sv_setnv() and newAV() and all their friends.
564       They're described in perlguts and perlapi.
565
566       Then you'll need to know how to manipulate the Perl stack.  That's
567       described in perlcall.
568
569       Once you've understood those, embedding Perl in C is easy.
570
571       Because C has no builtin function for integer exponentiation, let's
572       make Perl's ** operator available to it (this is less useful than it
573       sounds, because Perl implements ** with C's pow() function).  First
574       I'll create a stub exponentiation function in power.pl:
575
576           sub expo {
577               my ($a, $b) = @_;
578               return $a ** $b;
579           }
580
581       Now I'll create a C program, power.c, with a function PerlPower() that
582       contains all the perlguts necessary to push the two arguments into
583       expo() and to pop the return value out.  Take a deep breath...
584
585        #include <EXTERN.h>
586        #include <perl.h>
587
588        static PerlInterpreter *my_perl;
589
590        static void
591        PerlPower(int a, int b)
592        {
593          dSP;                            /* initialize stack pointer      */
594          ENTER;                          /* everything created after here */
595          SAVETMPS;                       /* ...is a temporary variable.   */
596          PUSHMARK(SP);                   /* remember the stack pointer    */
597          XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
598          XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
599          PUTBACK;                      /* make local stack pointer global */
600          call_pv("expo", G_SCALAR);      /* call the function             */
601          SPAGAIN;                        /* refresh stack pointer         */
602                                        /* pop the return value from stack */
603          printf ("%d to the %dth power is %d.\n", a, b, POPi);
604          PUTBACK;
605          FREETMPS;                       /* free that return value        */
606          LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
607        }
608
609        int main (int argc, char **argv, char **env)
610        {
611          char *my_argv[] = { "", "power.pl", NULL };
612
613          PERL_SYS_INIT3(&argc,&argv,&env);
614          my_perl = perl_alloc();
615          perl_construct( my_perl );
616
617          perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
618          PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
619          perl_run(my_perl);
620
621          PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/
622
623          perl_destruct(my_perl);
624          perl_free(my_perl);
625          PERL_SYS_TERM();
626          exit(EXIT_SUCCESS);
627        }
628
629       Compile and run:
630
631           % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
632
633           % power
634           3 to the 4th power is 81.
635
636   Maintaining a persistent interpreter
637       When developing interactive and/or potentially long-running
638       applications, it's a good idea to maintain a persistent interpreter
639       rather than allocating and constructing a new interpreter multiple
640       times.  The major reason is speed: since Perl will only be loaded into
641       memory once.
642
643       However, you have to be more cautious with namespace and variable
644       scoping when using a persistent interpreter.  In previous examples
645       we've been using global variables in the default package "main".  We
646       knew exactly what code would be run, and assumed we could avoid
647       variable collisions and outrageous symbol table growth.
648
649       Let's say your application is a server that will occasionally run Perl
650       code from some arbitrary file.  Your server has no way of knowing what
651       code it's going to run.  Very dangerous.
652
653       If the file is pulled in by "perl_parse()", compiled into a newly
654       constructed interpreter, and subsequently cleaned out with
655       "perl_destruct()" afterwards, you're shielded from most namespace
656       troubles.
657
658       One way to avoid namespace collisions in this scenario is to translate
659       the filename into a guaranteed-unique package name, and then compile
660       the code into that package using "eval" in perlfunc.  In the example
661       below, each file will only be compiled once.  Or, the application might
662       choose to clean out the symbol table associated with the file after
663       it's no longer needed.  Using "call_argv" in perlapi, We'll call the
664       subroutine "Embed::Persistent::eval_file" which lives in the file
665       "persistent.pl" and pass the filename and boolean cleanup/cache flag as
666       arguments.
667
668       Note that the process will continue to grow for each file that it uses.
669       In addition, there might be "AUTOLOAD"ed subroutines and other
670       conditions that cause Perl's symbol table to grow.  You might want to
671       add some logic that keeps track of the process size, or restarts itself
672       after a certain number of requests, to ensure that memory consumption
673       is minimized.  You'll also want to scope your variables with "my" in
674       perlfunc whenever possible.
675
676        package Embed::Persistent;
677        #persistent.pl
678
679        use strict;
680        our %Cache;
681        use Symbol qw(delete_package);
682
683        sub valid_package_name {
684            my($string) = @_;
685            $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
686            # second pass only for words starting with a digit
687            $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
688
689            # Dress it up as a real package name
690            $string =~ s|/|::|g;
691            return "Embed" . $string;
692        }
693
694        sub eval_file {
695            my($filename, $delete) = @_;
696            my $package = valid_package_name($filename);
697            my $mtime = -M $filename;
698            if(defined $Cache{$package}{mtime}
699               &&
700               $Cache{$package}{mtime} <= $mtime)
701            {
702               # we have compiled this subroutine already,
703               # it has not been updated on disk, nothing left to do
704               print STDERR "already compiled $package->handler\n";
705            }
706            else {
707               local *FH;
708               open FH, $filename or die "open '$filename' $!";
709               local($/) = undef;
710               my $sub = <FH>;
711               close FH;
712
713               #wrap the code into a subroutine inside our unique package
714               my $eval = qq{package $package; sub handler { $sub; }};
715               {
716                   # hide our variables within this block
717                   my($filename,$mtime,$package,$sub);
718                   eval $eval;
719               }
720               die $@ if $@;
721
722               #cache it unless we're cleaning out each time
723               $Cache{$package}{mtime} = $mtime unless $delete;
724            }
725
726            eval {$package->handler;};
727            die $@ if $@;
728
729            delete_package($package) if $delete;
730
731            #take a look if you want
732            #print Devel::Symdump->rnew($package)->as_string, $/;
733        }
734
735        1;
736
737        __END__
738
739        /* persistent.c */
740        #include <EXTERN.h>
741        #include <perl.h>
742
743        /* 1 = clean out filename's symbol table after each request,
744           0 = don't
745        */
746        #ifndef DO_CLEAN
747        #define DO_CLEAN 0
748        #endif
749
750        #define BUFFER_SIZE 1024
751
752        static PerlInterpreter *my_perl = NULL;
753
754        int
755        main(int argc, char **argv, char **env)
756        {
757            char *embedding[] = { "", "persistent.pl", NULL };
758            char *args[] = { "", DO_CLEAN, NULL };
759            char filename[BUFFER_SIZE];
760            int failing, exitstatus;
761
762            PERL_SYS_INIT3(&argc,&argv,&env);
763            if((my_perl = perl_alloc()) == NULL) {
764               fprintf(stderr, "no memory!");
765               exit(EXIT_FAILURE);
766            }
767            perl_construct(my_perl);
768
769            PL_origalen = 1; /* don't let $0 assignment update the
770                                proctitle or embedding[0] */
771            failing = perl_parse(my_perl, NULL, 2, embedding, NULL);
772            PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
773            if(!failing)
774               failing = perl_run(my_perl);
775            if(!failing) {
776               while(printf("Enter file name: ") &&
777                     fgets(filename, BUFFER_SIZE, stdin)) {
778
779                   filename[strlen(filename)-1] = '\0'; /* strip \n */
780                   /* call the subroutine,
781                            passing it the filename as an argument */
782                   args[0] = filename;
783                   call_argv("Embed::Persistent::eval_file",
784                                  G_DISCARD | G_EVAL, args);
785
786                   /* check $@ */
787                   if(SvTRUE(ERRSV))
788                       fprintf(stderr, "eval error: %s\n", SvPV_nolen(ERRSV));
789               }
790            }
791
792            PL_perl_destruct_level = 0;
793            exitstatus = perl_destruct(my_perl);
794            perl_free(my_perl);
795            PERL_SYS_TERM();
796            exit(exitstatus);
797        }
798
799       Now compile:
800
801        % cc -o persistent persistent.c \
802               `perl -MExtUtils::Embed -e ccopts -e ldopts`
803
804       Here's an example script file:
805
806        #test.pl
807        my $string = "hello";
808        foo($string);
809
810        sub foo {
811            print "foo says: @_\n";
812        }
813
814       Now run:
815
816        % persistent
817        Enter file name: test.pl
818        foo says: hello
819        Enter file name: test.pl
820        already compiled Embed::test_2epl->handler
821        foo says: hello
822        Enter file name: ^C
823
824   Execution of END blocks
825       Traditionally END blocks have been executed at the end of the perl_run.
826       This causes problems for applications that never call perl_run. Since
827       perl 5.7.2 you can specify "PL_exit_flags |= PERL_EXIT_DESTRUCT_END" to
828       get the new behaviour. This also enables the running of END blocks if
829       the perl_parse fails and "perl_destruct" will return the exit value.
830
831   $0 assignments
832       When a perl script assigns a value to $0 then the perl runtime will try
833       to make this value show up as the program name reported by "ps" by
834       updating the memory pointed to by the argv passed to perl_parse() and
835       also calling API functions like setproctitle() where available.  This
836       behaviour might not be appropriate when embedding perl and can be
837       disabled by assigning the value 1 to the variable "PL_origalen" before
838       perl_parse() is called.
839
840       The persistent.c example above is for instance likely to segfault when
841       $0 is assigned to if the "PL_origalen = 1;" assignment is removed.
842       This because perl will try to write to the read only memory of the
843       "embedding[]" strings.
844
845   Maintaining multiple interpreter instances
846       Some rare applications will need to create more than one interpreter
847       during a session.  Such an application might sporadically decide to
848       release any resources associated with the interpreter.
849
850       The program must take care to ensure that this takes place before the
851       next interpreter is constructed.  By default, when perl is not built
852       with any special options, the global variable "PL_perl_destruct_level"
853       is set to 0, since extra cleaning isn't usually needed when a program
854       only ever creates a single interpreter in its entire lifetime.
855
856       Setting "PL_perl_destruct_level" to 1 makes everything squeaky clean:
857
858        while(1) {
859            ...
860            /* reset global variables here with PL_perl_destruct_level = 1 */
861            PL_perl_destruct_level = 1;
862            perl_construct(my_perl);
863            ...
864            /* clean and reset _everything_ during perl_destruct */
865            PL_perl_destruct_level = 1;
866            perl_destruct(my_perl);
867            perl_free(my_perl);
868            ...
869            /* let's go do it again! */
870        }
871
872       When perl_destruct() is called, the interpreter's syntax parse tree and
873       symbol tables are cleaned up, and global variables are reset.  The
874       second assignment to "PL_perl_destruct_level" is needed because
875       perl_construct resets it to 0.
876
877       Now suppose we have more than one interpreter instance running at the
878       same time.  This is feasible, but only if you used the Configure option
879       "-Dusemultiplicity" or the options "-Dusethreads -Duseithreads" when
880       building perl.  By default, enabling one of these Configure options
881       sets the per-interpreter global variable "PL_perl_destruct_level" to 1,
882       so that thorough cleaning is automatic and interpreter variables are
883       initialized correctly.  Even if you don't intend to run two or more
884       interpreters at the same time, but to run them sequentially, like in
885       the above example, it is recommended to build perl with the
886       "-Dusemultiplicity" option otherwise some interpreter variables may not
887       be initialized correctly between consecutive runs and your application
888       may crash.
889
890       See also "Thread-aware system interfaces" in perlxs.
891
892       Using "-Dusethreads -Duseithreads" rather than "-Dusemultiplicity" is
893       more appropriate if you intend to run multiple interpreters
894       concurrently in different threads, because it enables support for
895       linking in the thread libraries of your system with the interpreter.
896
897       Let's give it a try:
898
899        #include <EXTERN.h>
900        #include <perl.h>
901
902        /* we're going to embed two interpreters */
903
904        #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
905
906        int main(int argc, char **argv, char **env)
907        {
908            PerlInterpreter *one_perl, *two_perl;
909            char *one_args[] = { "one_perl", SAY_HELLO, NULL };
910            char *two_args[] = { "two_perl", SAY_HELLO, NULL };
911
912            PERL_SYS_INIT3(&argc,&argv,&env);
913            one_perl = perl_alloc();
914            two_perl = perl_alloc();
915
916            PERL_SET_CONTEXT(one_perl);
917            perl_construct(one_perl);
918            PERL_SET_CONTEXT(two_perl);
919            perl_construct(two_perl);
920
921            PERL_SET_CONTEXT(one_perl);
922            perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
923            PERL_SET_CONTEXT(two_perl);
924            perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
925
926            PERL_SET_CONTEXT(one_perl);
927            perl_run(one_perl);
928            PERL_SET_CONTEXT(two_perl);
929            perl_run(two_perl);
930
931            PERL_SET_CONTEXT(one_perl);
932            perl_destruct(one_perl);
933            PERL_SET_CONTEXT(two_perl);
934            perl_destruct(two_perl);
935
936            PERL_SET_CONTEXT(one_perl);
937            perl_free(one_perl);
938            PERL_SET_CONTEXT(two_perl);
939            perl_free(two_perl);
940            PERL_SYS_TERM();
941            exit(EXIT_SUCCESS);
942        }
943
944       Note the calls to PERL_SET_CONTEXT().  These are necessary to
945       initialize the global state that tracks which interpreter is the
946       "current" one on the particular process or thread that may be running
947       it.  It should always be used if you have more than one interpreter and
948       are making perl API calls on both interpreters in an interleaved
949       fashion.
950
951       PERL_SET_CONTEXT(interp) should also be called whenever "interp" is
952       used by a thread that did not create it (using either perl_alloc(), or
953       the more esoteric perl_clone()).
954
955       Compile as usual:
956
957        % cc -o multiplicity multiplicity.c \
958         `perl -MExtUtils::Embed -e ccopts -e ldopts`
959
960       Run it, Run it:
961
962        % multiplicity
963        Hi, I'm one_perl
964        Hi, I'm two_perl
965
966   Using Perl modules, which themselves use C libraries, from your C program
967       If you've played with the examples above and tried to embed a script
968       that use()s a Perl module (such as Socket) which itself uses a C or C++
969       library, this probably happened:
970
971        Can't load module Socket, dynamic loading not available in this perl.
972         (You may need to build a new perl executable which either supports
973         dynamic loading or has the Socket module statically linked into it.)
974
975       What's wrong?
976
977       Your interpreter doesn't know how to communicate with these extensions
978       on its own.  A little glue will help.  Up until now you've been calling
979       perl_parse(), handing it NULL for the second argument:
980
981        perl_parse(my_perl, NULL, argc, my_argv, NULL);
982
983       That's where the glue code can be inserted to create the initial
984       contact between Perl and linked C/C++ routines. Let's take a look some
985       pieces of perlmain.c to see how Perl does this:
986
987        static void xs_init (pTHX);
988
989        EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
990        EXTERN_C void boot_Socket (pTHX_ CV* cv);
991
992
993        EXTERN_C void
994        xs_init(pTHX)
995        {
996               char *file = __FILE__;
997               /* DynaLoader is a special case */
998               newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
999               newXS("Socket::bootstrap", boot_Socket, file);
1000        }
1001
1002       Simply put: for each extension linked with your Perl executable
1003       (determined during its initial configuration on your computer or when
1004       adding a new extension), a Perl subroutine is created to incorporate
1005       the extension's routines.  Normally, that subroutine is named
1006       Module::bootstrap() and is invoked when you say use Module.  In turn,
1007       this hooks into an XSUB, boot_Module, which creates a Perl counterpart
1008       for each of the extension's XSUBs.  Don't worry about this part; leave
1009       that to the xsubpp and extension authors.  If your extension is
1010       dynamically loaded, DynaLoader creates Module::bootstrap() for you on
1011       the fly.  In fact, if you have a working DynaLoader then there is
1012       rarely any need to link in any other extensions statically.
1013
1014       Once you have this code, slap it into the second argument of
1015       perl_parse():
1016
1017        perl_parse(my_perl, xs_init, argc, my_argv, NULL);
1018
1019       Then compile:
1020
1021        % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
1022
1023        % interp
1024          use Socket;
1025          use SomeDynamicallyLoadedModule;
1026
1027          print "Now I can use extensions!\n"'
1028
1029       ExtUtils::Embed can also automate writing the xs_init glue code.
1030
1031        % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
1032        % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
1033        % cc -c interp.c  `perl -MExtUtils::Embed -e ccopts`
1034        % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
1035
1036       Consult perlxs, perlguts, and perlapi for more details.
1037
1038   Using embedded Perl with POSIX locales
1039       (See perllocale for information about these.)  When a Perl interpreter
1040       normally starts up, it tells the system it wants to use the system's
1041       default locale.  This is often, but not necessarily, the "C" or "POSIX"
1042       locale.  Absent a "use locale" within the perl code, this mostly has no
1043       effect (but see "Not within the scope of "use locale"" in perllocale).
1044       Also, there is not a problem if the locale you want to use in your
1045       embedded perl is the same as the system default.  However, this doesn't
1046       work if you have set up and want to use a locale that isn't the system
1047       default one.  Starting in Perl v5.20, you can tell the embedded Perl
1048       interpreter that the locale is already properly set up, and to skip
1049       doing its own normal initialization.  It skips if the environment
1050       variable "PERL_SKIP_LOCALE_INIT" is set (even if set to 0 or "").  A
1051       perl that has this capability will define the C pre-processor symbol
1052       "HAS_SKIP_LOCALE_INIT".  This allows code that has to work with
1053       multiple Perl versions to do some sort of work-around when confronted
1054       with an earlier Perl.
1055
1056       If your program is using the POSIX 2008 multi-thread locale
1057       functionality, you should switch into the global locale and set that up
1058       properly before starting the Perl interpreter.  It will then properly
1059       switch back to using the thread-safe functions.
1060

Hiding Perl_

1062       If you completely hide the short forms of the Perl public API, add
1063       -DPERL_NO_SHORT_NAMES to the compilation flags.  This means that for
1064       example instead of writing
1065
1066           warn("%d bottles of beer on the wall", bottlecount);
1067
1068       you will have to write the explicit full form
1069
1070           Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
1071
1072       (See "Background and PERL_IMPLICIT_CONTEXT" in perlguts for the
1073       explanation of the "aTHX_". )  Hiding the short forms is very useful
1074       for avoiding all sorts of nasty (C preprocessor or otherwise) conflicts
1075       with other software packages (Perl defines about 2400 APIs with these
1076       short names, take or leave few hundred, so there certainly is room for
1077       conflict.)
1078

MORAL

1080       You can sometimes write faster code in C, but you can always write code
1081       faster in Perl.  Because you can use each from the other, combine them
1082       as you wish.
1083

AUTHOR

1085       Jon Orwant <orwant@media.mit.edu> and Doug MacEachern
1086       <dougm@covalent.net>, with small contributions from Tim Bunce, Tom
1087       Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
1088       Zakharevich.
1089
1090       Doug MacEachern has an article on embedding in Volume 1, Issue 4 of The
1091       Perl Journal ( <http://www.tpj.com/> ).  Doug is also the developer of
1092       the most widely-used Perl embedding: the mod_perl system
1093       (perl.apache.org), which embeds Perl in the Apache web server.  Oracle,
1094       Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl have used
1095       this model for Oracle, Netscape and Internet Information Server Perl
1096       plugins.
1097
1099       Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant.
1100       All Rights Reserved.
1101
1102       This document may be distributed under the same terms as Perl itself.
1103
1104
1105
1106perl v5.34.1                      2022-03-15                      PERLEMBED(1)
Impressum