Serge Tsafak > Parallel-ThreadContext > Parallel::ThreadContext

Download:
Parallel-ThreadContext-0.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source  

NAME ^

ThreadContext - Framework for easy creation of multithreaded Perl programs.

Features ^

version

  return the current version information for this module
  
  arguments: none
  
  returns:
    version info of this module

start

  create and run a thread group to perform specific queue jobs 
  all threads in the group will run the same code with different data and will share the same queue and same locks
  we say that they run in the same context.
  
  arguments:
    reference to code to be executed by each thread (mandatory)
    reference to array data (jobs) to be distributed to each thread (mandatory)
    number of threads to be started (mandatory)
    name to assign to this context of execution (optional, default context is assumed otherwise)
  
  returns: none

end

  terminate execution in the given context
  all affected threads will be asked to return (eventually wait till they have finished processing the queue)
  
  arguments:
    name of context (optional, default context is assumed otherwise)
  
  returns:
    reference to hash containing the return values from each exited thread (thread id is hash key)

addJobsToQueue

  push additional jobs onto the queue in the given context
  
  arguments:
    reference to array data (jobs) which will be pushed onto the queue (mandatory)
    name of context (optional, default context is assumed otherwise)
  
  returns: none

finalizeQueue

  prevent adding jobs in the given context (irreversible)
  affected threads will then known that their task is done and they can safely return as soon as queue is empty
  
  arguments:
    name of context (optional, default context is assumed otherwise)
  
  returns: none

reserveLock

  request and lock a resource
  any attempt to reserve the same lock will block until lock is released
  required for synchronisation of threads in the same context
  
  arguments:
    name of lock to be reserved (mandatory)
    name of context (optional, default context is assumed otherwise)
  
  returns: none

releaseLock

  release a previously locked resource
  any attempt to reserve the same lock will succeed after lock is released
  required for synchronisation of threads in the same context
  
  arguments:
    name of lock to be released (mandatory)
    name of context (optional, default context is assumed otherwise)
  
  returns: none

getContextName

  returns the name of context where calling thread is currently executed
  
  arguments: none
  
  returns:
    context name

getNoProcessors

  returns the number of machine processors as returned by underlying OS
  Most of Windows and UNIX-like systems supported
  
  arguments: none
  
  returns:
    number of processors on machine

shareVariable

  Make the variable (scalar, array, hash) referenced by the given argument visible to all threads (shared variable)
  A depth of up to 10 references is allowed (reference to reference to ... to variable)
  
  arguments:
    reference to variable to be shared (mandatory)
  
  returns: none

yieldRuntime

  ask threads in the given context to yield some runtime to threads in other contexts
  how long they will let processor to other threads depend on the underlying OS
  
  arguments:
    name of context (optional, default context is assumed otherwise)
  
  returns: none

pauseCurrentThread

  pause the calling thread for the given time length in seconds.

  arguments:
    time length the thread shall pause
  
  returns: none

println

  print the given message by indicating source (Thread ID) and timestamp.

  arguments:
    message to be printed out
    
  returns: none

abortCurrentThread

  abort calling thread and print the given message by indicating source (Thread ID) and timestamp before

  arguments:
    message to be printed before exit
    
  returns: none

Synopsis ^

  use Parallel::ThreadContext;

  my $counter = 0;
  my $counter_ref = \$counter;
  
  sub op1
  {
    my $job = shift @_;
    Parallel::ThreadContext::abortCurrentThread("I am tired of living") if ($job == 30);
    Parallel::ThreadContext::println("performing job $job in Context ".Parallel::ThreadContext::getContextName());
    Parallel::ThreadContext::pauseCurrentThread(1);
    Parallel::ThreadContext::reserveLock("counterlock","computation");
    $counter++;
    Parallel::ThreadContext::releaseLock("counterlock","computation");
  }
  
  $Parallel::ThreadContext::debug = 1;
  print STDOUT Parallel::ThreadContext::version();
  my $nbthreads = Parallel::ThreadContext::getNoProcessors();
  if (defined $nbthreads)
  {
  $nbthreads *= 3; #3 threads per processor
  }
  else
  {
  $nbthreads = 3;
  }
  Parallel::ThreadContext::shareVariable($counter_ref);
  Parallel::ThreadContext::start(\&op1,[1..10],$nbthreads,"computation");
  Parallel::ThreadContext::addJobsToQueue([11..20],"computation");
  Parallel::ThreadContext::pauseCurrentThread(2);
  Parallel::ThreadContext::addJobsToQueue([21..26],"computation");
  Parallel::ThreadContext::pauseCurrentThread(4);
  Parallel::ThreadContext::end("computation"); #would give a warning if queue in the context is still open (not finalized yet)
  Parallel::ThreadContext::addJobsToQueue([27..30],"computation"); #warning since mentioned context does no longer exist
  Parallel::ThreadContext::addJobsToQueue([27..30],"computation");
  Parallel::ThreadContext::start(\&op1,[],1,"computation2");
  Parallel::ThreadContext::finalizeQueue("computation2");
  Parallel::ThreadContext::yieldRuntime("computation2");
  Parallel::ThreadContext::end("computation2");
  Parallel::ThreadContext::println("final counter value is $counter");

Description ^

  This module provides a framework and some utilities for easy creation of multithreaded Perl programs.
  It introduces and uses the concept of context based concurrent threads. 
  A context specifies a kind of name and work space for thread execution and consists of a queue + threads working on that queue + locks used by threads working on that queue.
  User can freely define as many contexts as he wants depending on its application logic e.g. 'prefetch', 'decode', 'execute', ...
  In each context threads are performing concurrent similar jobs on the same queue.
  All threads in the same context represent a thread group. Of course a group can consist of one thread only.
  Resources locked in one context do not affect other contexts.

Bugs and Caveats ^

  No known bugs at this time, but this doesn't mean there are aren't any. Use it at your own risk.
  Note that there may be other bugs or limitations that the author is not aware of.

Author ^

  Serge Tsafak <tsafserge2001@yahoo.fr>

Copyright ^

  This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

History ^

 Version 0.0.1: first release; August 2008
syntax highlighting: