wx::thread(3) [osx man page]

Wx::Thread(3)						User Contributed Perl Documentation					     Wx::Thread(3)

NAME

       Thread - using wxPerl with threads

SYNOPSIS

	 # 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( &work );

	 # create frames, etc
	 my $frame = Wx::Frame->new( ... );
	 EVT_COMMAND( $frame, -1, $DONE_EVENT, &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( ... );
	 }

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.

       Order of module loading

       It's necessary for "use Wx" to happen after <use threads::shared>.

       Sending events from worker threads

       "Wx::PlThreadEvent" can be used to communicate between worker and GUI threads.  The event can carry a shared value between threads.

	 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 );
	 }

       The target of the event can be any "Wx::EvtHandler"

       Receiving events from worker threads

       "Wx::PlThreadEvent" is a command event and can be handled as such.  The "->GetData" method can be used to retrieve the shared data
       contained inside the event.

	 my $DONE_EVENT : shared = Wx::NewEventType;

	 EVT_COMMAND( $frame, -1, $DONE_EVENT, &done );

	 sub done {
	     my( $frame, $event ) = @_;

	     print $event->GetData;
	 }

       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 @_ before starting the thread.

       For example:

	 sub OnCreateThread {
	     my( $self, $event ) = @_; @_ = ();

	     threads->create( ... );
	 }

       failure to do that will cause "scalars leaked" warnings from the Perl interpreter.

perl v5.10.0							    2007-04-28							     Wx::Thread(3)

iv_work(3)						    ivykis programmer's manual							iv_work(3)

NAME

       IV_WORK_POOL_INIT, iv_work_pool_create, iv_work_pool_put, IV_WORK_ITEM_INIT, iv_work_pool_submit_work - ivykis worker thread management

SYNOPSIS

       #include <iv_work.h>

       struct iv_work_pool {
	       int	       max_threads;
	       void	       *cookie;
	       void	       (*thread_start)(void *cookie);
	       void	       (*thread_stop)(void *cookie);
       };

       struct iv_work_item {
	       void	       *cookie;
	       void	       (*work)(void *cookie);
	       void	       (*completion)(void *cookie);
       };

       void IV_WORK_POOL_INIT(struct iv_work_pool *this);
       int iv_work_pool_create(struct iv_work_pool *this);
       int iv_work_pool_put(struct iv_work_pool *this);
       void IV_WORK_ITEM_INIT(struct iv_work_item *work);
       int iv_work_pool_submit_work(struct iv_work_pool *this, struct iv_work_item *work);

DESCRIPTION

       Calling	iv_work_pool_create  on  a struct iv_work_pool object previously initialised by IV_WORK_POOL_INIT creates a pool of worker threads
       that can be used to offload CPU intensive tasks to, so as to prevent negatively influencing event handling latency in the  calling  thread,
       and to enable the use of multiple host CPUs for CPU intensive tasks.

       iv_work	dynamically  adjusts  the  number of threads in the pool to the amount of work there is to do.	The ->max_threads member of struct
       iv_work_pool specifies the maximum number of threads that will be created in this pool.

       Calling iv_work_pool_submit_work on a struct iv_work_item object previously initialised by IV_WORK_ITEM_INIT submits a work item to a pool.
       The  ->work  member of struct iv_work_item specifies the function that will be called in one of the worker threads in the pool specified by
       ->this, with ->cookie as its sole argument.  When the work function has completed, iv_work will call the ->completion callback to  indicate
       this, also with ->cookie as its sole argument, in the thread that iv_work_pool_create was called in for this pool object.

       As  a  special  case,  calling iv_work_pool_submit_work with a NULL work pool pointer will cause the work item to be processed in the local
       thread, from an iv_task(3) callback.

       If the ->thread_start function pointer specified in struct iv_work_pool is not NULL, it will be	called	upon  creation	of  a  new  worker
       thread,	in the context of the created worker thread, with ->cookie as its sole argument.  Calls to ->thread_start are not explicitly seri-
       alised, which should be kept in mind when manipulating state shared between threads from within that callback function.

       Similarly, if iv_work decides to terminate a worker thread, for example due to inactivity, ->thread_stop will be called in the  context	of
       the terminating thread, with ->cookie as its sole argument.  Calls to ->thread_stop are also not explicitly serialised.

       iv_work_pool_submit_work can only be called from the thread that iv_work_pool_create for this pool object was called in.

       There is no way to cancel submitted work items.

       There is no guaranteed order, FIFO or otherwise, between different work items submitted to the same worker thread pool.

       When the user has no more work items to submit to the pool, its reference to the pool can be dropped by calling iv_work_pool_put.

       If  there  are still pending or running work items assigned to this pool when iv_work_pool_put is called, those work items will not be can-
       celed, but will be allowed to run to completion, and their ->completion callbacks will be called as usual.  A similar thing holds  for  the
       ->thread_start  and  ->thread_stop  callbacks  -- they can also still be called after iv_work_pool_put returns.	Even so, the memory corre-
       sponding to the struct iv_work_pool can immediately be freed or reused by the user upon return of the iv_work_pool_put call.

       Internally, iv_work uses iv_thread(3) for its thread management.

SEE ALSO

       ivykis(3), iv_thread(3)

ivykis								    2010-09-14								iv_work(3)