fiber.h

The Spectral Toolkit is a C++ spectral transform library written by Rodney James and Chuck Panaccion

//
// spectral toolkit 
// copyright (c) 2005 university corporation for atmospheric research
// licensed under the gnu general public license
//

#ifndef __fiber__
#define __fiber__

#include <pthread.h>

/// Internal function that invokes start method from a thread.

extern "C" void* fiber_wrapper(void*);

namespace spectral
{
  /// Abstract base class for lightweight threads.
  /// Provides a lightweight abstract interface to the POSIX thread API
  /// through inheritance.  The virtual start method is invoked when the
  /// thread is started by calling the spawn method.  A thread is joined 
  /// or terminated when the join method returns.
  /// See Walmsley, Mark, <I>Multi-Threaded Programming in C++</I>, Springer-Verlag, 1999.
  ///
  /// One way to use the fiber object is to associate a thread with an object;
  /// that is, when a new object is instantiated, information is passed through
  /// the constructor and a thread started.  The destructor when called then blocks
  /// until the thread terminates, cleaning up the thread.  This mechanism provides
  /// a natural way to map thread creation and destruction to objects.  Following is
  /// an example of how to do this, using the included thread class template.
  /// \code
  ///
  /// #include "fiber.h"
  ///
  /// namespace spectral
  /// {
  ///   template <typename A,void(F)(A)> class thread : public fiber
  ///   {
  ///   private:
  ///     A a;
  ///     void start() { F(a); }
  ///   public:
  ///     thread(A arg) : a(arg) { spawn(); }
  ///     ~thread() { join(); };
  ///   };
  /// }
  /// \endcode
  /// 
  /// Here, the type A is specified along with a void function F taking one argument
  /// of type A.  This function is called when the thread is started, with the value
  /// of the constructor, of type A, passed to the thread.
  ///
  /// Below is a program that uses the thread class template and a group to perform
  /// a concurrent sum over three threads.  
  /// \code
  /// #include <thread.h>
  /// #include <group.h>
  /// #include <iostream>
  ///
  /// using namespace spectral;
  /// 
  /// group *G;
  /// 
  /// double sum;
  /// 
  /// void func(double x)
  /// {
  ///   lock(G);
  ///   sum+=x;
  ///   unlock(G);
  /// }
  /// 
  /// typedef thread<double,func> Thread;
  /// 
  /// int main()
  /// {
  ///   G=new group(3);
  ///   sum=0.0;
  ///   Thread *T1=new Thread(1.0);
  ///   Thread *T2=new Thread(2.0);
  ///   Thread *T3=new Thread(3.0);
  ///   delete T1;
  ///   delete T2;
  ///   delete T3;
  ///   delete G;
  ///   std::cout << "sum=" << sum << std::endl;
  ///   return(0);
  /// }
  /// \endcode
  ///
  /// \sa group

  class fiber
  {
  public:
    fiber();
    virtual void start()=0;
    virtual ~fiber();
  protected:
    int spawn();
    void* join();
  private:
    /// Internal POSIX thread identifier.
    pthread_t tid;
    /// Internal POSIX thread attribute;
    pthread_attr_t attr;
    /// Internal flag set when thread is started.
    long running;
  };
}
#endif

// Local Variables:
// mode:C++
// End: