- NAME
- Features

- version
- start
- end
- addJobsToQueue
- finalizeQueue
- reserveLock
- releaseLock
- getContextName
- getNoProcessors
- shareVariable
- yieldRuntime
- pauseCurrentThread
- println
- abortCurrentThread

- Synopsis
- Description
- Bugs and Caveats
- Author
- Copyright
- History

# 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