perlembed.1

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

\& already compiled Embed::test_2epl\->handler
\& foo says: hello
\& Enter file name: ^C
.Ve
.Sh "Execution of \s-1END\s0 blocks"
.IX Subsection "Execution of END blocks"
Traditionally \s-1END\s0 blocks have been executed at the end of the perl_run.
This causes problems for applications that never call perl_run. Since
perl 5.7.2 you can specify \f(CW\*(C`PL_exit_flags |= PERL_EXIT_DESTRUCT_END\*(C'\fR
to get the new behaviour. This also enables the running of \s-1END\s0 blocks if
the perl_parse fails and \f(CW\*(C`perl_destruct\*(C'\fR will return the exit value.
.ie n .Sh "$0 assignments"
.el .Sh "\f(CW$0\fP assignments"
.IX Subsection "$0 assignments"
When a perl script assigns a value to \f(CW$0\fR then the perl runtime will
try to make this value show up as the program name reported by \*(L"ps\*(R" by
updating the memory pointed to by the argv passed to \fIperl_parse()\fR and
also calling \s-1API\s0 functions like \fIsetproctitle()\fR where available.  This
behaviour might not be appropriate when embedding perl and can be
disabled by assigning the value \f(CW1\fR to the variable \f(CW\*(C`PL_origalen\*(C'\fR
before \fIperl_parse()\fR is called.
.PP
The \fIpersistent.c\fR example above is for instance likely to segfault
when \f(CW$0\fR is assigned to if the \f(CW\*(C`PL_origalen = 1;\*(C'\fR assignment is
removed.  This because perl will try to write to the read only memory
of the \f(CW\*(C`embedding[]\*(C'\fR strings.
.Sh "Maintaining multiple interpreter instances"
.IX Subsection "Maintaining multiple interpreter instances"
Some rare applications will need to create more than one interpreter
during a session.  Such an application might sporadically decide to
release any resources associated with the interpreter.
.PP
The program must take care to ensure that this takes place \fIbefore\fR
the next interpreter is constructed.  By default, when perl is not
built with any special options, the global variable
\&\f(CW\*(C`PL_perl_destruct_level\*(C'\fR is set to \f(CW0\fR, since extra cleaning isn't
usually needed when a program only ever creates a single interpreter
in its entire lifetime.
.PP
Setting \f(CW\*(C`PL_perl_destruct_level\*(C'\fR to \f(CW1\fR makes everything squeaky clean:
.PP
.Vb 10
\& while(1) {
\&     ...
\&     /* reset global variables here with PL_perl_destruct_level = 1 */
\&     PL_perl_destruct_level = 1;
\&     perl_construct(my_perl);
\&     ...
\&     /* clean and reset _everything_ during perl_destruct */
\&     PL_perl_destruct_level = 1;
\&     perl_destruct(my_perl);
\&     perl_free(my_perl);
\&     ...
\&     /* let\*(Aqs go do it again! */
\& }
.Ve
.PP
When \fI\fIperl_destruct()\fI\fR is called, the interpreter's syntax parse tree
and symbol tables are cleaned up, and global variables are reset.  The
second assignment to \f(CW\*(C`PL_perl_destruct_level\*(C'\fR is needed because
perl_construct resets it to \f(CW0\fR.
.PP
Now suppose we have more than one interpreter instance running at the
same time.  This is feasible, but only if you used the Configure option
\&\f(CW\*(C`\-Dusemultiplicity\*(C'\fR or the options \f(CW\*(C`\-Dusethreads \-Duseithreads\*(C'\fR when
building perl.  By default, enabling one of these Configure options
sets the per-interpreter global variable \f(CW\*(C`PL_perl_destruct_level\*(C'\fR to
\&\f(CW1\fR, so that thorough cleaning is automatic and interpreter variables
are initialized correctly.  Even if you don't intend to run two or
more interpreters at the same time, but to run them sequentially, like
in the above example, it is recommended to build perl with the
\&\f(CW\*(C`\-Dusemultiplicity\*(C'\fR option otherwise some interpreter variables may
not be initialized correctly between consecutive runs and your
application may crash.
.PP
See also \*(L"Thread-aware system interfaces\*(R" in perlxs.
.PP
Using \f(CW\*(C`\-Dusethreads \-Duseithreads\*(C'\fR rather than \f(CW\*(C`\-Dusemultiplicity\*(C'\fR
is more appropriate if you intend to run multiple interpreters
concurrently in different threads, because it enables support for
linking in the thread libraries of your system with the interpreter.
.PP
Let's give it a try:
.PP
.Vb 2
\& #include <EXTERN.h>
\& #include <perl.h>
\&
\& /* we\*(Aqre going to embed two interpreters */
\& /* we\*(Aqre going to embed two interpreters */
\&
\& #define SAY_HELLO "\-e", "print qq(Hi, I\*(Aqm $^X\en)"
\&
\& int main(int argc, char **argv, char **env)
\& {
\&     PerlInterpreter *one_perl, *two_perl;
\&     char *one_args[] = { "one_perl", SAY_HELLO };
\&     char *two_args[] = { "two_perl", SAY_HELLO };
\&
\&     PERL_SYS_INIT3(&argc,&argv,&env);
\&     one_perl = perl_alloc();
\&     two_perl = perl_alloc();
\&
\&     PERL_SET_CONTEXT(one_perl);
\&     perl_construct(one_perl);
\&     PERL_SET_CONTEXT(two_perl);
\&     perl_construct(two_perl);
\&
\&     PERL_SET_CONTEXT(one_perl);
\&     perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
\&     PERL_SET_CONTEXT(two_perl);
\&     perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
\&
\&     PERL_SET_CONTEXT(one_perl);
\&     perl_run(one_perl);
\&     PERL_SET_CONTEXT(two_perl);
\&     perl_run(two_perl);
\&
\&     PERL_SET_CONTEXT(one_perl);
\&     perl_destruct(one_perl);
\&     PERL_SET_CONTEXT(two_perl);
\&     perl_destruct(two_perl);
\&
\&     PERL_SET_CONTEXT(one_perl);
\&     perl_free(one_perl);
\&     PERL_SET_CONTEXT(two_perl);
\&     perl_free(two_perl);
\&     PERL_SYS_TERM();
\& }
.Ve
.PP
Note the calls to \s-1\fIPERL_SET_CONTEXT\s0()\fR.  These are necessary to initialize
the global state that tracks which interpreter is the \*(L"current\*(R" one on
the particular process or thread that may be running it.  It should
always be used if you have more than one interpreter and are making
perl \s-1API\s0 calls on both interpreters in an interleaved fashion.
.PP
\&\s-1PERL_SET_CONTEXT\s0(interp) should also be called whenever \f(CW\*(C`interp\*(C'\fR is
used by a thread that did not create it (using either \fIperl_alloc()\fR, or
the more esoteric \fIperl_clone()\fR).
.PP
Compile as usual:
.PP
.Vb 1
\& % cc \-o multiplicity multiplicity.c \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
.Ve
.PP
Run it, Run it:
.PP
.Vb 3
\& % multiplicity
\& Hi, I\*(Aqm one_perl
\& Hi, I\*(Aqm two_perl
.Ve
.Sh "Using Perl modules, which themselves use C libraries, from your C program"
.IX Subsection "Using Perl modules, which themselves use C libraries, from your C program"
If you've played with the examples above and tried to embed a script
that \fI\fIuse()\fI\fRs a Perl module (such as \fISocket\fR) which itself uses a C or \*(C+ library,
this probably happened:
.PP
.Vb 3
\& Can\*(Aqt load module Socket, dynamic loading not available in this perl.
\&  (You may need to build a new perl executable which either supports
\&  dynamic loading or has the Socket module statically linked into it.)
.Ve
.PP
What's wrong?
.PP
Your interpreter doesn't know how to communicate with these extensions
on its own.  A little glue will help.  Up until now you've been
calling \fI\fIperl_parse()\fI\fR, handing it \s-1NULL\s0 for the second argument:
.PP
.Vb 1
\& perl_parse(my_perl, NULL, argc, my_argv, NULL);
.Ve
.PP
That's where the glue code can be inserted to create the initial contact between
Perl and linked C/\*(C+ routines.  Let's take a look some pieces of \fIperlmain.c\fR
to see how Perl does this:
.PP
.Vb 1
\& static void xs_init (pTHX);
\&
\& EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
\& EXTERN_C void boot_Socket (pTHX_ CV* cv);
\&
\&
\& EXTERN_C void
\& xs_init(pTHX)
\& {
\&        char *file = _\|_FILE_\|_;
\&        /* DynaLoader is a special case */
\&        newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
\&        newXS("Socket::bootstrap", boot_Socket, file);
\& }
.Ve
.PP
Simply put: for each extension linked with your Perl executable
(determined during its initial configuration on your
computer or when adding a new extension),
a Perl subroutine is created to incorporate the extension's
routines.  Normally, that subroutine is named
\&\fI\fIModule::bootstrap()\fI\fR and is invoked when you say \fIuse Module\fR.  In
turn, this hooks into an \s-1XSUB\s0, \fIboot_Module\fR, which creates a Perl
counterpart for each of the extension's XSUBs.  Don't worry about this
part; leave that to the \fIxsubpp\fR and extension authors.  If your
extension is dynamically loaded, DynaLoader creates \fI\fIModule::bootstrap()\fI\fR
for you on the fly.  In fact, if you have a working DynaLoader then there
is rarely any need to link in any other extensions statically.
.PP
Once you have this code, slap it into the second argument of \fI\fIperl_parse()\fI\fR:
.PP
.Vb 1
\& perl_parse(my_perl, xs_init, argc, my_argv, NULL);
.Ve
.PP
Then compile:
.PP
.Vb 1
\& % cc \-o interp interp.c \`perl \-MExtUtils::Embed \-e ccopts \-e ldopts\`
\&
\& % interp
\&   use Socket;
\&   use SomeDynamicallyLoadedModule;
\&
\&   print "Now I can use extensions!\en"\*(Aq
.Ve
.PP
\&\fBExtUtils::Embed\fR can also automate writing the \fIxs_init\fR glue code.
.PP
.Vb 4
\& % perl \-MExtUtils::Embed \-e xsinit \-\- \-o perlxsi.c
\& % cc \-c perlxsi.c \`perl \-MExtUtils::Embed \-e ccopts\`
\& % cc \-c interp.c  \`perl \-MExtUtils::Embed \-e ccopts\`
\& % cc \-o interp perlxsi.o interp.o \`perl \-MExtUtils::Embed \-e ldopts\`
.Ve
.PP
Consult perlxs, perlguts, and perlapi for more details.
.SH "Embedding Perl under Win32"
.IX Header "Embedding Perl under Win32"
In general, all of the source code shown here should work unmodified under
Windows.
.PP
However, there are some caveats about the command-line examples shown.
For starters, backticks won't work under the Win32 native command shell.
The ExtUtils::Embed kit on \s-1CPAN\s0 ships with a script called
\&\fBgenmake\fR, which generates a simple makefile to build a program from
a single C source file.  It can be used like this:
.PP
.Vb 3
\& C:\eExtUtils\-Embed\eeg> perl genmake interp.c
\& C:\eExtUtils\-Embed\eeg> nmake
\& C:\eExtUtils\-Embed\eeg> interp \-e "print qq{I\*(Aqm embedded in Win32!\en}"
.Ve
.PP
You may wish to use a more robust environment such as the Microsoft
Developer Studio.  In this case, run this to generate perlxsi.c:
.PP
.Vb 1
\& perl \-MExtUtils::Embed \-e xsinit
.Ve
.PP
Create a new project and Insert \-> Files into Project: perlxsi.c,
perl.lib, and your own source files, e.g. interp.c.  Typically you'll
find perl.lib in \fBC:\eperl\elib\eCORE\fR, if not, you should see the
\&\fB\s-1CORE\s0\fR directory relative to \f(CW\*(C`perl \-V:archlib\*(C'\fR.  The studio will
also need this path so it knows where to find Perl include files.
This path can be added via the Tools \-> Options \-> Directories menu.
Finally, select Build \-> Build interp.exe and you're ready to go.
.SH "Hiding Perl_"
.IX Header "Hiding Perl_"
If you completely hide the short forms forms of the Perl public \s-1API\s0,
add \-DPERL_NO_SHORT_NAMES to the compilation flags.  This means that
for example instead of writing
.PP
.Vb 1
\&    warn("%d bottles of beer on the wall", bottlecount);
.Ve
.PP
you will have to write the explicit full form
.PP
.Vb 1
\&    Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
.Ve
.PP
(See "Background and \s-1PERL_IMPLICIT_CONTEXT\s0 for the explanation
of the \f(CW\*(C`aTHX_\*(C'\fR." in perlguts )  Hiding the short forms is very useful for avoiding
all sorts of nasty (C preprocessor or otherwise) conflicts with other
software packages (Perl defines about 2400 APIs with these short names,
take or leave few hundred, so there certainly is room for conflict.)
.SH "MORAL"
.IX Header "MORAL"
You can sometimes \fIwrite faster code\fR in C, but
you can always \fIwrite code faster\fR in Perl.  Because you can use
each from the other, combine them as you wish.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jon Orwant <\[e-mail]\fR> and Doug MacEachern
<\[e-mail]\fR>, with small contributions from Tim Bunce, Tom
Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
Zakharevich.
.PP
Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
The Perl Journal ( http://www.tpj.com/ ).  Doug is also the developer of the
most widely-used Perl embedding: the mod_perl system
(perl.apache.org), which embeds Perl in the Apache web server.
Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
have used this model for Oracle, Netscape and Internet Information
Server Perl plugins.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant.  All
Rights Reserved.
.PP
Permission is granted to make and distribute verbatim copies of this
documentation provided the copyright notice and this permission notice are
preserved on all copies.
.PP
Permission is granted to copy and distribute modified versions of this
documentation under the conditions for verbatim copying, provided also
that they are marked clearly as modified versions, that the authors'
names and title are unchanged (though subtitles and additional
authors' names may be added), and that the entire resulting derived
work is distributed under the terms of a permission notice identical
to this one.
.PP
Permission is granted to copy and distribute translations of this
documentation into another language, under the above conditions for
modified versions.