git.maemo.org Git - pkg-perl/blob - deb-src/libwx-perl/libwx-perl-0.96/blib/lib/Wx/Thread.pod

   1 =head1 NAME
   2
   3 Thread - using wxPerl with threads
   4
   5 =head1 SYNOPSIS
   6
   7   # the order of these use()s is important
   8   use threads;
   9   use threads::shared;
  10   use Wx;
  11
  12   my $DONE_EVENT : shared = Wx::NewEventType;
  13
  14   my $worker = threads->create( \&work );
  15
  16   # create frames, etc
  17   my $frame = Wx::Frame->new( ... );
  18   EVT_COMMAND( $frame, -1, $DONE_EVENT, \&done );
  19   $app->MainLoop;
  20
  21   sub done {
  22       my( $frame, $event ) = @_;
  23
  24       print $event->GetData;
  25   }
  26
  27   sub work {
  28       # ... do stuff, create a shared $result value
  29
  30       my $threvent = new Wx::PlThreadEvent( -1, $DONE_EVENT, $result );
  31       Wx::PostEvent( $frame, $threvent );
  32   }
  33
  34   # event handler
  35   sub OnCreateThread {
  36       # @_ = () is necessary to avoid "Scalars leaked"
  37       my( $self, $event ) = @_; @_ = ();
  38
  39       threads->create( ... );
  40   }
  41
  42 =head1 DESCRIPTION
  43
  44 Threaded GUI application are somewhat different from non-GUI threaded
  45 applications in that the main thread (which runs the GUI) must never
  46 block.  Also, in wxWidgets, no thread other than the main thread can
  47 manipulate GUI objects.  This leads to a hybrid model where worker
  48 threads must send events to the main thread in order to change the GUI
  49 state or signal their termination.
  50
  51 =head2 Order of module loading
  52
  53 It's necessary for C<use Wx> to happen after <use threads::shared>.
  54
  55 =head2 Sending events from worker threads
  56
  57 C<Wx::PlThreadEvent> can be used to communicate between worker and
  58 GUI threads.  The event can carry a I<shared> value between threads.
  59
  60   my $DONE_EVENT : shared = Wx::NewEventType;
  61
  62   sub work {
  63       # ... do some stuff
  64       my $progress = new Wx::PlThreadEvent( -1, $DONE_EVENT, $progress );
  65       Wx::PostEvent( $frame, $progress );
  66
  67       # ... do stuff, create a shared $result value
  68       my $end = new Wx::PlThreadEvent( -1, $DONE_EVENT, $result );
  69       Wx::PostEvent( $frame, $end );
  70   }
  71
  72 The target of the event can be any C<Wx::EvtHandler>
  73
  74 =head2 Receiving events from worker threads
  75
  76 C<Wx::PlThreadEvent> is a command event and can be handled as such.
  77 The C<< ->GetData >> method can be used to retrieve the I<shared> data
  78 contained inside the event.
  79
  80   my $DONE_EVENT : shared = Wx::NewEventType;
  81
  82   EVT_COMMAND( $frame, -1, $DONE_EVENT, \&done );
  83
  84   sub done {
  85       my( $frame, $event ) = @_;
  86
  87       print $event->GetData;
  88   }
  89
  90 =head2 Creating new threads
  91
  92 Creating new threads from event handlers works without problems except
  93 from a little snag.  In order not to trigger a bug in the Perl
  94 interpreter, all event handler that directly or indirectly cause a
  95 thread creation must clean C<@_> before starting the thread.
  96
  97 For example:
  98
  99   sub OnCreateThread {
 100       my( $self, $event ) = @_; @_ = ();
 101
 102       threads->create( ... );
 103   }
 104
 105 failure to do that will cause "scalars leaked" warnings from the Perl
 106 interpreter.
 107
 108 =cut