.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Wx::Thread 3pm"
.TH Wx::Thread 3pm 2024-04-11 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Thread \- using wxPerl with threads
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&  # the order of these use()s is important
\&  use threads;
\&  use threads::shared;
\&  use Wx;
\&
\&  my $DONE_EVENT : shared = Wx::NewEventType;
\&
\&  my $worker = threads\->create( \e&work );
\&
\&  # create frames, etc
\&  my $frame = Wx::Frame\->new( ... );
\&  EVT_COMMAND( $frame, \-1, $DONE_EVENT, \e&done );
\&  $app\->MainLoop;
\&
\&  sub done {
\&      my( $frame, $event ) = @_;
\&
\&      print $event\->GetData;
\&  }
\&
\&  sub work {
\&      # ... do stuff, create a shared $result value
\&
\&      my $threvent = new Wx::PlThreadEvent( \-1, $DONE_EVENT, $result );
\&      Wx::PostEvent( $frame, $threvent );
\&  }
\&
\&  # event handler
\&  sub OnCreateThread {
\&      # @_ = () is necessary to avoid "Scalars leaked"
\&      my( $self, $event ) = @_; @_ = ();
\&
\&      threads\->create( ... );
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Threaded GUI application are somewhat different from non-GUI threaded
applications in that the main thread (which runs the GUI) must never
block.  Also, in wxWidgets, no thread other than the main thread can
manipulate GUI objects.  This leads to a hybrid model where worker
threads must send events to the main thread in order to change the GUI
state or signal their termination.
.SS "Order of module loading"
.IX Subsection "Order of module loading"
It's necessary for \f(CW\*(C`use Wx\*(C'\fR to happen after <use threads::shared>.
.SS "Sending events from worker threads"
.IX Subsection "Sending events from worker threads"
\&\f(CW\*(C`Wx::PlThreadEvent\*(C'\fR can be used to communicate between worker and
GUI threads.  The event can carry a \fIshared\fR value between threads.
.PP
.Vb 1
\&  my $DONE_EVENT : shared = Wx::NewEventType;
\&
\&  sub work {
\&      # ... do some stuff
\&      my $progress = new Wx::PlThreadEvent( \-1, $DONE_EVENT, $progress );
\&      Wx::PostEvent( $frame, $progress );
\&
\&      # ... do stuff, create a shared $result value
\&      my $end = new Wx::PlThreadEvent( \-1, $DONE_EVENT, $result );
\&      Wx::PostEvent( $frame, $end );
\&  }
.Ve
.PP
The target of the event can be any \f(CW\*(C`Wx::EvtHandler\*(C'\fR
.SS "Receiving events from worker threads"
.IX Subsection "Receiving events from worker threads"
\&\f(CW\*(C`Wx::PlThreadEvent\*(C'\fR is a command event and can be handled as such.
The \f(CW\*(C`\->GetData\*(C'\fR method can be used to retrieve the \fIshared\fR data
contained inside the event.
.PP
.Vb 1
\&  my $DONE_EVENT : shared = Wx::NewEventType;
\&
\&  EVT_COMMAND( $frame, \-1, $DONE_EVENT, \e&done );
\&
\&  sub done {
\&      my( $frame, $event ) = @_;
\&
\&      print $event\->GetData;
\&  }
.Ve
.SS "Creating new threads"
.IX Subsection "Creating new threads"
Creating new threads from event handlers works without problems except
from a little snag.  In order not to trigger a bug in the Perl
interpreter, all event handler that directly or indirectly cause a
thread creation must clean \f(CW@_\fR before starting the thread.
.PP
For example:
.PP
.Vb 2
\&  sub OnCreateThread {
\&      my( $self, $event ) = @_; @_ = ();
\&
\&      threads\->create( ... );
\&  }
.Ve
.PP
failure to do that will cause "scalars leaked" warnings from the Perl
interpreter.