threads.3

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

.IX Item "threads->detach()"
Class method that allows a thread to detach itself.
.IP "threads\->\fIself()\fR" 4
.IX Item "threads->self()"
Class method that allows a thread to obtain its own \fIthreads\fR object.
.ie n .IP "$thr\fR\->\fItid()" 4
.el .IP "\f(CW$thr\fR\->\fItid()\fR" 4
.IX Item "$thr->tid()"
Returns the \s-1ID\s0 of the thread.  Thread IDs are unique integers with the main
thread in a program being 0, and incrementing by 1 for every thread created.
.IP "threads\->\fItid()\fR" 4
.IX Item "threads->tid()"
Class method that allows a thread to obtain its own \s-1ID\s0.
.ie n .IP """$thr""" 4
.el .IP "``$thr''" 4
.IX Item "$thr"
If you add the \f(CW\*(C`stringify\*(C'\fR import option to your \f(CW\*(C`use threads\*(C'\fR declaration,
then using a threads object in a string or a string context (e.g., as a hash
key) will cause its \s-1ID\s0 to be used as the value:
.Sp
.Vb 1
\&    use threads qw(stringify);
\&
\&    my $thr = threads\->create(...);
\&    print("Thread $thr started...\en");  # Prints out: Thread 1 started...
.Ve
.IP "threads\->object($tid)" 4
.IX Item "threads->object($tid)"
This will return the \fIthreads\fR object for the \fIactive\fR thread associated
with the specified thread \s-1ID\s0.  Returns \f(CW\*(C`undef\*(C'\fR if there is no thread
associated with the \s-1TID\s0, if the thread is joined or detached, if no \s-1TID\s0 is
specified or if the specified \s-1TID\s0 is undef.
.IP "threads\->\fIyield()\fR" 4
.IX Item "threads->yield()"
This is a suggestion to the \s-1OS\s0 to let this thread yield \s-1CPU\s0 time to other
threads.  What actually happens is highly dependent upon the underlying
thread implementation.
.Sp
You may do \f(CW\*(C`use threads qw(yield)\*(C'\fR, and then just use \f(CW\*(C`yield()\*(C'\fR in your
code.
.IP "threads\->\fIlist()\fR" 4
.IX Item "threads->list()"
.PD 0
.IP "threads\->list(threads::all)" 4
.IX Item "threads->list(threads::all)"
.IP "threads\->list(threads::running)" 4
.IX Item "threads->list(threads::running)"
.IP "threads\->list(threads::joinable)" 4
.IX Item "threads->list(threads::joinable)"
.PD
With no arguments (or using \f(CW\*(C`threads::all\*(C'\fR) and in a list context, returns a
list of all non-joined, non-detached \fIthreads\fR objects.  In a scalar context,
returns a count of the same.
.Sp
With a \fItrue\fR argument (using \f(CW\*(C`threads::running\*(C'\fR), returns a list of all
non-joined, non-detached \fIthreads\fR objects that are still running.
.Sp
With a \fIfalse\fR argument (using \f(CW\*(C`threads::joinable\*(C'\fR), returns a list of all
non-joined, non-detached \fIthreads\fR objects that have finished running (i.e.,
for which \f(CW\*(C`\->join()\*(C'\fR will not \fIblock\fR).
.ie n .IP "$thr1\->equal($thr2)" 4
.el .IP "\f(CW$thr1\fR\->equal($thr2)" 4
.IX Item "$thr1->equal($thr2)"
Tests if two threads objects are the same thread or not.  This is overloaded
to the more natural forms:
.Sp
.Vb 7
\&    if ($thr1 == $thr2) {
\&        print("Threads are the same\en");
\&    }
\&    # or
\&    if ($thr1 != $thr2) {
\&        print("Threads differ\en");
\&    }
.Ve
.Sp
(Thread comparison is based on thread IDs.)
.IP "async \s-1BLOCK\s0;" 4
.IX Item "async BLOCK;"
\&\f(CW\*(C`async\*(C'\fR creates a thread to execute the block immediately following
it.  This block is treated as an anonymous subroutine, and so must have a
semicolon after the closing brace.  Like \f(CW\*(C`threads\->create()\*(C'\fR, \f(CW\*(C`async\*(C'\fR
returns a \fIthreads\fR object.
.ie n .IP "$thr\fR\->\fIerror()" 4
.el .IP "\f(CW$thr\fR\->\fIerror()\fR" 4
.IX Item "$thr->error()"
Threads are executed in an \f(CW\*(C`eval\*(C'\fR context.  This method will return \f(CW\*(C`undef\*(C'\fR
if the thread terminates \fInormally\fR.  Otherwise, it returns the value of
\&\f(CW$@\fR associated with the thread's execution status in its \f(CW\*(C`eval\*(C'\fR context.
.ie n .IP "$thr\fR\->\fI_handle()" 4
.el .IP "\f(CW$thr\fR\->\fI_handle()\fR" 4
.IX Item "$thr->_handle()"
This \fIprivate\fR method returns the memory location of the internal thread
structure associated with a threads object.  For Win32, this is a pointer to
the \f(CW\*(C`HANDLE\*(C'\fR value returned by \f(CW\*(C`CreateThread\*(C'\fR (i.e., \f(CW\*(C`HANDLE *\*(C'\fR); for other
platforms, it is a pointer to the \f(CW\*(C`pthread_t\*(C'\fR structure used in the
\&\f(CW\*(C`pthread_create\*(C'\fR call (i.e., \f(CW\*(C`pthread_t *\*(C'\fR).
.Sp
This method is of no use for general Perl threads programming.  Its intent is
to provide other (XS-based) thread modules with the capability to access, and
possibly manipulate, the underlying thread structure associated with a Perl
thread.
.IP "threads\->\fI_handle()\fR" 4
.IX Item "threads->_handle()"
Class method that allows a thread to obtain its own \fIhandle\fR.
.SH "EXITING A THREAD"
.IX Header "EXITING A THREAD"
The usual method for terminating a thread is to
\&\fIreturn()\fR from the entry point function with the
appropriate return value(s).
.IP "threads\->\fIexit()\fR" 4
.IX Item "threads->exit()"
If needed, a thread can be exited at any time by calling
\&\f(CW\*(C`threads\->exit()\*(C'\fR.  This will cause the thread to return \f(CW\*(C`undef\*(C'\fR in a
scalar context, or the empty list in a list context.
.Sp
When called from the \fImain\fR thread, this behaves the same as \f(CWexit(0)\fR.
.IP "threads\->exit(status)" 4
.IX Item "threads->exit(status)"
When called from a thread, this behaves like \f(CW\*(C`threads\->exit()\*(C'\fR (i.e., the
exit status code is ignored).
.Sp
When called from the \fImain\fR thread, this behaves the same as \f(CW\*(C`exit(status)\*(C'\fR.
.IP "\fIdie()\fR" 4
.IX Item "die()"
Calling \f(CW\*(C`die()\*(C'\fR in a thread indicates an abnormal exit for the thread.  Any
\&\f(CW$SIG{_\|_DIE_\|_}\fR handler in the thread will be called first, and then the
thread will exit with a warning message that will contain any arguments passed
in the \f(CW\*(C`die()\*(C'\fR call.
.IP "exit(status)" 4
.IX Item "exit(status)"
Calling \fIexit()\fR inside a thread causes the whole
application to terminate.  Because of this, the use of \f(CW\*(C`exit()\*(C'\fR inside
threaded code, or in modules that might be used in threaded applications, is
strongly discouraged.
.Sp
If \f(CW\*(C`exit()\*(C'\fR really is needed, then consider using the following:
.Sp
.Vb 2
\&    threads\->exit() if threads\->can(\*(Aqexit\*(Aq);   # Thread friendly
\&    exit(status);
.Ve
.IP "use threads 'exit' => 'threads_only'" 4
.IX Item "use threads 'exit' => 'threads_only'"
This globally overrides the default behavior of calling \f(CW\*(C`exit()\*(C'\fR inside a
thread, and effectively causes such calls to behave the same as
\&\f(CW\*(C`threads\->exit()\*(C'\fR.  In other words, with this setting, calling \f(CW\*(C`exit()\*(C'\fR
causes only the thread to terminate.
.Sp
Because of its global effect, this setting should not be used inside modules
or the like.
.Sp
The \fImain\fR thread is unaffected by this setting.
.IP "threads\->create({'exit' => 'thread_only'}, ...)" 4
.IX Item "threads->create({'exit' => 'thread_only'}, ...)"
This overrides the default behavior of \f(CW\*(C`exit()\*(C'\fR inside the newly created
thread only.
.ie n .IP "$thr\->set_thread_exit_only(boolean)" 4
.el .IP "\f(CW$thr\fR\->set_thread_exit_only(boolean)" 4
.IX Item "$thr->set_thread_exit_only(boolean)"
This can be used to change the \fIexit thread only\fR behavior for a thread after
it has been created.  With a \fItrue\fR argument, \f(CW\*(C`exit()\*(C'\fR will cause only the
thread to exit.  With a \fIfalse\fR argument, \f(CW\*(C`exit()\*(C'\fR will terminate the
application.
.Sp
The \fImain\fR thread is unaffected by this call.
.IP "threads\->set_thread_exit_only(boolean)" 4
.IX Item "threads->set_thread_exit_only(boolean)"
Class method for use inside a thread to change its own behavior for \f(CW\*(C`exit()\*(C'\fR.
.Sp
The \fImain\fR thread is unaffected by this call.
.SH "THREAD STATE"
.IX Header "THREAD STATE"
The following boolean methods are useful in determining the \fIstate\fR of a
thread.
.ie n .IP "$thr\fR\->\fIis_running()" 4
.el .IP "\f(CW$thr\fR\->\fIis_running()\fR" 4
.IX Item "$thr->is_running()"
Returns true if a thread is still running (i.e., if its entry point function
has not yet finished or exited).
.ie n .IP "$thr\fR\->\fIis_joinable()" 4
.el .IP "\f(CW$thr\fR\->\fIis_joinable()\fR" 4
.IX Item "$thr->is_joinable()"
Returns true if the thread has finished running, is not detached and has not
yet been joined.  In other words, the thread is ready to be joined, and a call
to \f(CW\*(C`$thr\->join()\*(C'\fR will not \fIblock\fR.
.ie n .IP "$thr\fR\->\fIis_detached()" 4
.el .IP "\f(CW$thr\fR\->\fIis_detached()\fR" 4
.IX Item "$thr->is_detached()"
Returns true if the thread has been detached.
.IP "threads\->\fIis_detached()\fR" 4
.IX Item "threads->is_detached()"
Class method that allows a thread to determine whether or not it is detached.
.SH "THREAD CONTEXT"
.IX Header "THREAD CONTEXT"
As with subroutines, the type of value returned from a thread's entry point
function may be determined by the thread's \fIcontext\fR:  list, scalar or void.
The thread's context is determined at thread creation.  This is necessary so
that the context is available to the entry point function via
\&\fIwantarray()\fR.  The thread may then specify a value of
the appropriate type to be returned from \f(CW\*(C`\->join()\*(C'\fR.
.Sh "Explicit context"
.IX Subsection "Explicit context"
Because thread creation and thread joining may occur in different contexts, it
may be desirable to state the context explicitly to the thread's entry point
function.  This may be done by calling \f(CW\*(C`\->create()\*(C'\fR with a hash reference
as the first argument:
.PP
.Vb 3
\&    my $thr = threads\->create({\*(Aqcontext\*(Aq => \*(Aqlist\*(Aq}, \e&foo);
\&    ...
\&    my @results = $thr\->join();
.Ve
.PP
In the above, the threads object is returned to the parent thread in scalar
context, and the thread's entry point function \f(CW\*(C`foo\*(C'\fR will be called in list
(array) context such that the parent thread can receive a list (array) from
the \f(CW\*(C`\->join()\*(C'\fR call.  (\f(CW\*(Aqarray\*(Aq\fR is synonymous with \f(CW\*(Aqlist\*(Aq\fR.)
.PP
Similarly, if you need the threads object, but your thread will not be
returning a value (i.e., \fIvoid\fR context), you would do the following:
.PP
.Vb 3
\&    my $thr = threads\->create({\*(Aqcontext\*(Aq => \*(Aqvoid\*(Aq}, \e&foo);
\&    ...
\&    $thr\->join();
.Ve
.PP
The context type may also be used as the \fIkey\fR in the hash reference followed
by a \fItrue\fR value:
.PP
.Vb 4
\&    threads\->create({\*(Aqscalar\*(Aq => 1}, \e&foo);
\&    ...
\&    my ($thr) = threads\->list();
\&    my $result = $thr\->join();
.Ve
.Sh "Implicit context"
.IX Subsection "Implicit context"
If not explicitly stated, the thread's context is implied from the context
of the \f(CW\*(C`\->create()\*(C'\fR call:
.PP
.Vb 2
\&    # Create thread in list context
\&    my ($thr) = threads\->create(...);
\&
\&    # Create thread in scalar context
\&    my $thr = threads\->create(...);
\&
\&    # Create thread in void context
\&    threads\->create(...);
.Ve
.ie n .Sh "$thr\fP\->\fIwantarray()"
.el .Sh "\f(CW$thr\fP\->\fIwantarray()\fP"
.IX Subsection "$thr->wantarray()"
This returns the thread's context in the same manner as
\&\fIwantarray()\fR.
.Sh "threads\->\fIwantarray()\fP"
.IX Subsection "threads->wantarray()"
Class method to return the current thread's context.  This returns the same
value as running \fIwantarray()\fR inside the current
thread's entry point function.
.SH "THREAD STACK SIZE"
.IX Header "THREAD STACK SIZE"
The default per-thread stack size for different platforms varies
significantly, and is almost always far more than is needed for most
applications.  On Win32, Perl's makefile explicitly sets the default stack to
16 \s-1MB\s0; on most other platforms, the system default is used, which again may be
much larger than is needed.
.PP
By tuning the stack size to more accurately reflect your application's needs,
you may significantly reduce your application's memory usage, and increase the
number of simultaneously running threads.
.PP
Note that on Windows, address space allocation granularity is 64 \s-1KB\s0,
therefore, setting the stack smaller than that on Win32 Perl will not save any
more memory.
.IP "threads\->\fIget_stack_size()\fR;" 4
.IX Item "threads->get_stack_size();"
Returns the current default per-thread stack size.  The default is zero, which
means the system default stack size is currently in use.
.ie n .IP "$size\fR = \f(CW$thr\fR\->\fIget_stack_size();" 4
.el .IP "\f(CW$size\fR = \f(CW$thr\fR\->\fIget_stack_size()\fR;" 4
.IX Item "$size = $thr->get_stack_size();"
Returns the stack size for a particular thread.  A return value of zero
indicates the system default stack size was used for the thread.
.ie n .IP "$old_size = threads\->set_stack_size($new_size);" 4
.el .IP "\f(CW$old_size\fR = threads\->set_stack_size($new_size);" 4
.IX Item "$old_size = threads->set_stack_size($new_size);"
Sets a new default per-thread stack size, and returns the previous setting.
.Sp
Some platforms have a minimum thread stack size.  Trying to set the stack size
below this value will result in a warning, and the minimum stack size will be
used.
.Sp
Some Linux platforms have a maximum stack size.  Setting too large of a stack
size will cause thread creation to fail.
.Sp
If needed, \f(CW$new_size\fR will be rounded up to the next multiple of the memory
page size (usually 4096 or 8192).
.Sp
Threads created after the stack size is set will then either call
\&\f(CW\*(C`pthread_attr_setstacksize()\*(C'\fR \fI(for pthreads platforms)\fR, or supply the
stack size to \f(CW\*(C`CreateThread()\*(C'\fR \fI(for Win32 Perl)\fR.
.Sp
(Obviously, this call does not affect any currently extant threads.)
.IP "use threads ('stack_size' => \s-1VALUE\s0);" 4
.IX Item "use threads ('stack_size' => VALUE);"
This sets the default per-thread stack size at the start of the application.
.ie n .IP "$ENV{'\s-1PERL5_ITHREADS_STACK_SIZE\s0'}" 4
.el .IP "\f(CW$ENV\fR{'\s-1PERL5_ITHREADS_STACK_SIZE\s0'}" 4
.IX Item "$ENV{'PERL5_ITHREADS_STACK_SIZE'}"
The default per-thread stack size may be set at the start of the application
through the use of the environment variable \f(CW\*(C`PERL5_ITHREADS_STACK_SIZE\*(C'\fR:
.Sp
.Vb 3
\&    PERL5_ITHREADS_STACK_SIZE=1048576
\&    export PERL5_ITHREADS_STACK_SIZE
\&    perl \-e\*(Aquse threads; print(threads\->get_stack_size(), "\en")\*(Aq
.Ve
.Sp
This value overrides any \f(CW\*(C`stack_size\*(C'\fR parameter given to \f(CW\*(C`use threads\*(C'\fR.  Its
primary purpose is to permit setting the per-thread stack size for legacy
threaded applications.
.IP "threads\->create({'stack_size' => \s-1VALUE\s0}, \s-1FUNCTION\s0, \s-1ARGS\s0)" 4
.IX Item "threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)"
To specify a particular stack size for any individual thread, call
\&\f(CW\*(C`\->create()\*(C'\fR with a hash reference as the first argument:
.Sp
.Vb 1
\&    my $thr = threads\->create({\*(Aqstack_size\*(Aq => 32*4096}, \e&foo, @args);
.Ve
.ie n .IP "$thr2\fR = \f(CW$thr1\->create(\s-1FUNCTION\s0, \s-1ARGS\s0)" 4