thread_cond.h

多线程库

#ifndef __THREADS_COND_H
#define __THREADS_COND_H

#include <thread_mutex.h>
#include <thread_attributes.h>
#include <thread_spinlock.h>

class wait_queue;

/**
 * Cond, is a conditional semaphore.  A process can wait on a
 * specific condition... and another, can trigger that condition
 * through this class.
 *
 * One typical example of use of this kind of class, is the
 * producer consumer example:
 *
 * <pre>
 *
 * #include <thread.h>
 * #include <string>
 *
 * string produced;
 * mutex lock;
 * cond signal;
 *
 * class producer : public pthread {
 *  public:
 *    producer() { };
 *    ~producer() { };
 *    int thread(void *) {
 *       char buf[80];
 *
 *       lock.lock();
 *       cin.geline(buf,80);
 *       produced = buf;
 *       signal.signal();
 *       lock.unlock();
 *    };
 * };
 *
 * class consumer : public pthread {
 *  public:
 *    consumer() { };
 *    ~consumer() { };
 *
 *    int thread(void *) {
 *       lock.lock();
 *       signal.wait();
 *       cout << "Production was '" << s.c_str() << "'\n";
 *       lock.unlock();
 *    }
 * }
 *
 * main()
 * {
 *   pthread = p;
 * 
 *   p new consumer;
 *   (void)new producer;
 *   p.join();
 * }
 *
 * </pre>
 *
 * Notice the order, in which the two threads are created.  The consumer
 * before the producer.  This is because both of these threads start by
 * locking the mutex lock, and the consumer must be the first one to
 * actually acquire it.
 * 
 * @short Class for signalling conditions between processes.
 * @author Orn Hansen <[e-mail]>
 */
class cond {
 private:
  static char *c_project;
  int c_id;
  attributes::scope c_scope;
  wait_queue *c_waiting;

 public:
  cond(attributes::scope);
  cond();
  ~cond();

  /**
   * Each condition variable, can have one of the
   * following scopes.
   *
   * <pre>
   * process_shared     - interprocess
   * process_private    - only within this process and its threads.
   * </pre>
   *
   * @return The scope of this condition variable.
   */
  attributes::scope scope();
  /**
   * This method, waits until a signal has been received
   * and suspends the calling process during that period.  The
   * thread can be cancelled, while waiting for the signal.
   *
   * @param mutex A mutex variable, which is unlocked during the period and locked immediately after.
   * @return Always returns 0, signifying success.
   */
  int wait(mutex&);
  /**
   * This method, acts in a similar manner to the one above,
   * but it will timeout on the wait when a specific time tick
   * has been reached. Take a look at @ref #timedwait_rel 
   * for a discussion on possible return values.
   * @see #timedwait_rel for a discussion on the kinds
   * of return values that are available.
   *
   * @param mutex Mutex variable to lock on signal.
   * @param timespec The time tick, when a timeout should occur.
   */
  int timedwait(mutex&, const struct timespec *);
  /**
   * This method is equivalent to the above, except that the
   * time specification it accepts is a relative time.  Instead
   * of specifying the absolute time tick to timeout, it specifies
   * the amount of time to wait, until a timeout should occurr.
   * This method will return a value, specifying the cause of
   * return from it.  It can be one of:
   * <pre>
   *   ESRCH          - If the calling thread is not known to the system.
   *   EINTR          - If an interrupt signal was received and terminated the wait.
   *   ETIMEOUT       - If a timeout occurred, prior to receiving a signal.
   *   0              - On success.
   * </pre>
   *
   * @param mutex The mutex to lock, when signal has been received.
   * @param timespec A structure with the amount of time to wait for a signal, before timing out.
   */
  int timedwait_rel(mutex&, const struct timespec *);
  /**
   * This method, will send a signal to the next process that is
   * registered in the waiting processes list.  That process will
   * be revived.
   *
   * @return Always return 0, signifying success.
   */
  int signal();
  /**
   * This method, will send a signal to every process on the waiting
   * processes list, reviving them all.  All processes will be removed
   * from the waiting queue.
   *
   * @return Always return 0, signifying success.
   */
  int broadcast();
  /**
   * The shared memory scheme, wants a single name to identify the
   * overall program.  It is possible, and perhaps desired that
   * part cond/mutex/semaphore have their own name identification
   * tree.  This is possible, by stating that it should be branch
   * of the main file name, with a give extension.
   *
   * <pre>
   * main()
   * {
   *   cond *cv;
   *
   *   pthread::set_project( "my_project" );
   *   cond::project_par( "cond" );
   *   cv = new cond(attributes::process_shared);
   *   ...
   * }
   * </pre>
   *
   * This will set the project to my_project, and all condition
   * variables will be derived from my_project_cond.
   *
   * @param part A C string containing the cond part name.
   */
  static void project_part(const char *);
};

#endif /* THREADS COND */