---

more/cf/thread.h

Go to the documentation of this file.

//  more/thread.h -- a thread class: POSIX implementation
//  Copyright (C) 1998--2002  Petter Urkedal

//  This file is free software; you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation; either version 2 of the License, or
//  (at your option) any later version.

//  This file is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.

//  You should have received a copy of the GNU General Public License
//  along with this program; if not, write to the Free Software
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

//  As a special exception, you may use this file as part of a free
//  software library without restriction.  Specifically, if other files
//  instantiate templates or use macros or inline functions from this
//  file, or you compile this file and link it with other files to
//  produce an executable, this file does not by itself cause the
//  resulting executable to be covered by the GNU General Public
//  License.  This exception does not however invalidate any other
//  reasons why the executable file might be covered by the GNU General
//  Public License.

//  $Id: thread.h,v 1.2 2002/08/24 13:59:38 petter_urkedal Exp $


#ifndef MORE_CF_THREAD_H
#define MORE_CF_THREAD_H

#include <exception>
#include <stdexcept>
#include <more/bits/configdefs.h>
#include <more/gen/utility.h>
#include <more/gen/closure.h>
#include <more/cf/threadfwd.h>


namespace more {
namespace cf {


  //--------------------------------------------------------------------
  //                            mutex
  //--------------------------------------------------------------------

  class mutex_data;

  /** Mutual exclusive lock.  Mutex locks are used to prevent
      different threads from accessing the same collection of
      interdependent data simultaneously.  If the conditions given for
      the member functions are violated, a logic_error will be thrown.
      Also, runtime_error may be throw in case of lack of
      resources. */
  struct mutex : gen::handle<mutex_data>
  {
      friend class mutex_data;

      //! The non-trivial default ctor initializes a new mutex.
      mutex();

      //! Copy ctor with shallow-copy semantic.
      mutex(mutex const&);

      //! Destructor.
      /*! The destructor requires that the mutex is currently unlocked. */
      ~mutex();

      //! Assignment with shallow-copy semantic.
      mutex& operator=(mutex const&);

      //! Lock the mutex.
      /*! The mutex must not be already locked in the same thread.  If
       *  it is locked by another thread, this call will suspend the
       *  current thread until it is unlocked. */
      void lock();

      //! Lock the mutex if it is unlocked.
      /*! Same as lock(), except that when the mutex is locked by
       *  another thread, this call exits with false. Otherwise it
       *  exits with true. */
      bool trylock();

      //! Unlock a mutex.
      // The mutex must be previously locked by the current thread.
      void unlock();
  };



  //--------------------------------------------------------------------
  //                            thread
  //--------------------------------------------------------------------

  class thread_data;

  /** A descriptor for creating and controlling a thread.  */
  class thread : gen::handle<thread_data>
  {
      typedef gen::generator_closure<void> closure_type;

    public:
      /** Construct an undefined thread object.  This object becomes
          defined afther assigning another thread object or calling
          set_call. */
      thread();

      /** Construct a shallow copy of x. */
      thread(thread const& x);

      /** Destruct a thread descriptor.  The thread data will be
          released when all instances of thread is out of scope and
          the thread has returned. */
      ~thread();

      /** Construct a thread which will run the given closure when
          started.  This is equivalend to default construction
          followed by a set_call. */
      explicit thread(closure_type const&);

      /** Assign a shallow copy of x. */
      thread& operator=(thread const& x);

    private:
      explicit thread(thread_data*);

    public:
      /** Returns is_defined(). */
      operator bool() { return this->data(); }

      /** Set the closure to call.  The thread must not have been
          started.  */
      void set_call(closure_type const&);

      /** True iff a closue has been assigned to the thread. */
      bool is_defined() const;

      /** True iff the thread has been started. */
      bool is_started() const;

      /** True iff the thread is started and has not yet returned. */
      bool is_active() const;

      /** True iff the thread is running. */
      bool is_running() const;

      /** True iff the thread has returned. */
      bool is_finished() const;

      /** True iff the thread cancel() method has been called for this
          thread.  The thread has not necessarily acknowledged this
          and may still be running. */
      bool is_canceled() const;

      /** True iff an exception was raised in the thread. Implies
          is_finished(). */
      bool is_excepted() const;

      /** Start the given closure in a new thread. */
      void start();

      /** Throw a thread_cancel exception in the thread.  The
          cancellation will be acknowledged only after the code calls
          checkpoint(). */
      void cancel();

      /** Wait for a thread to stop.  Uncaught exceptions, but not
          thread_canceled, will be rethrown, but with loss of
          type-information.  That is, exceptions derived from
          exception, logic_error or runtime error will be rethrown as
          this base class. */
      bool join();  // returns true if computation is complete

      friend class thread_data;
      friend thread thread_of_caller();
  };

  /** True iff cancel is requested for this thread. */
  bool caller_is_canceled();

#if MORE_BW(20011111)
  /** DON'T USE, backward compatibility. */
  inline bool is_canceled() { return caller_is_canceled(); }
#endif

  /** The thread descriptor of the thread from which this function is
      called. The main thread returns an undefined descriptor at the
      moment, though this may change. */
  thread thread_of_caller();

  /** The exception thrown by checkpoint() if cancel() is called on
      the current thread. */
  struct thread_canceled {};

}} // namespace more::cf

#endif

---