thread.h

多线程库

  bool joinable() const;
  /**
   * If a thread has terminated its run, this status will
   * be stored for parent threads to examine.
   *
   * @return True if the thread has terminated its running loop. 
   */
  bool terminated() const           { return p_terminated; };
  /**
   * There are several ways, as previously mentioned, for a thread
   * to finish.  One way, is that it uses the 'exit()' call belonging
   * to the class, another that it simply 'returns' from the
   * loop.
   *
   * @return True, if the thread has exited with 'exit'.
   */
  bool exited() const               { return p_exited; };

  /**
   * Return the cancel state of the process.  The process
   * can disable cancelation, which will make it useful to
   * be able to check if it is actually possible to cancel
   * it.  The cancel state can be one of:
   *
   * <pre>
   * cancel_enable   - The process can be cancelled.
   * cancel_disable  - The process cannot be cancelled.
   * </pre>
   *
   * @return The cancel state.
   */
  cancel_state cancelstate() const  { return p_cancelstate; };
  /**
   * If cancels occur, the process can treat them in one of
   * two ways.  It can be handled asynchronously, or it can
   * deferred.  Cancel type, is thus one of:
   *
   * <pre>
   * cancel_deferred      - Cancels are deferred.
   * cancel_asynchronous  - Asynchronous cancels.
   * </pre>
   *
   * @return the cancel type.
   */
  cancel_type canceltype() const    { return p_canceltype; };

  /**
   * Join this thread, with another thread.  When this
   * thread terminates, the joined process will be signalled
   * to revive it from a slumber, as a result.
   *
   * @param pid The pid of the process to revive on exit.
   * @return The pid that was set.
   */
  int joining(int s)                { return p_joining = s; };

  /**
   * Set the cancelation state for this thread, see
   * @ref #cancelstate for a discussion on the states available.
   */
  void set(cancel_state s)          { p_cancelstate = s; };
  /**
   * Set the cancelation type for this thread, see
   * @ref #canceltype for a discussion on the types that
   * are available.
   */
  void set(cancel_type t)           { p_canceltype = t; };
  /**
   * Set the points to jump to, on cancel or signal signals.  The
   * jump types are:
   *
   * <pre>
   * cancel_jmp   - When a cancel signal occurs.
   * signal_jmp   - On a normal signal.
   * </pre>
   *
   * @param jump the jump kind, as above.
   * @param sigjmp The jump point to set.
   */
  void set(jumps, sigjmp_buf *);
  /**
   * Set any of the boolean variables this thread contains.  The
   * following are for use:
   *
   * <pre>
   * set_canceled       - Signify cancel state.
   * set_terminated     - Signify termination state.
   * set_detached       - Signify detached state.
   * set_exited         - Signify exited state.
   * </pre>
   * 
   * The state can only be set, by the process owner.  In this case,
   * the thread itself.
   * @param type The type, as above.
   * @param bool A boolean value, to set to.
   */
  void set(booleans, bool);

  /**
   * Cancel the process.  This will halt the threads execution,
   * set the cancel state to cancel.  If the cancel type is
   * asynchronous, it will also exit the main loop with an exit
   * value of -1, else if the cancel type is deferred it will
   * jump to a location specified.
   */
  void cancel();
  /**
   * Suspend the process.  The process is halted, but not
   * terminated... a suspended process cannot be cancelled,
   * unless it has been suspended with that in mind
   * see @ref #suspend_with_cancellation
   * The process will be restarted,  upon receiving a restart
   * signal see @ref #restart
   */
  static void suspend();
  /**
   * suspend the calling process, until it is cancelled or
   * receives a signal.  This does the same thing as @ref #suspend
   * but unlike it, the thread can be cancelled when waiting
   * for a signal inside this function.
   */
  static void suspend_with_cancelation();
  /**
   * restart the thread, associated with the class instance.  This
   * will in effect send a SIGUSR1 signal to the process, which will
   * wake it up, if it is in a suspended state or otherwise won't
   * do a thing.
   */
  void restart();

  /**
   * Jump to a given location, look at @ref #set for a discussion on
   * how to set the location to jump to.
   */
  void jump(jumps);

  /**
   * exit the process, with a given return value.  This will only
   * work if the calling process is the same as the thread running
   * inside the class instance.  Calling this function from a
   * parent thread, will not have any effect on this class's thread
   * but rather on the calling thread.
   */
  void exit(void *);
  /**
   * exit the process as above, but give a retcode as a result
   * insteaad of a pointer to a return value.
   */
  void exit(int);
  /**
   * exit the process as above, but give the normal zero return
   * value.
   */
  void exit()                       { this->exit(0); };

  /**
   * If a thread exits with 'return val' from inside the thread
   * function, the return value will be stored and retreivable
   * through this function.
   *
   * @return The return value of the thread.
   */
  int retcode();

  /**
   * Tell if the process of the thread instance is running.  This
   * function is really not very useful, it calls the scheduler
   * to see if it has the thread scheduled.  Which the scheduler
   * does, even if the thread is a zombie.  See @ref #terminated
   * and @ref #cancelled for different methods in determining
   * wether the thread is still alive.
   */
  bool running();

  /**
   * Join the calling process, with the thread instance.  This
   * will suspend the calling process, until the thread has
   * terminated.  The call can return one of the following
   * error values:
   *
   * <pre>
   *  EDLCK         - Dead lock would occur.
   *  ESRCH         - The process is not in the list.
   *  EINVAL        - The thread is detached, or already joining another.
   *  0             - The thread has terminated.
   * </pre>
   * @return err A value, as seen above.
   */
  int join();

  /**
   * In a shared environment, each process must have it's system wide
   * project name that uniquely identifies it and enables other
   * processes to identify its resources for sharing.  This method is
   * provided to change the current project identity to your hearts
   * desire.
   *
   * Note: these project id's will be created as filenames inside
   * the tmp directory, during the process run.  This is done because
   * the shared memory key scheme want's an inode number for use in
   * shared memory key creation.
   *
   * @param str A C string, giving the name of a common project.
   */
  static void set_project(const char *);

  /**
   * In creating a project, the default permission scheme used is
   * RW-R--R-- i.e. Read Write for the user, and Read permission for
   * everyone else.  The user however, may want a different scheme
   * in sharing his pages, for which purpose this is provided.
   *
   * @param perm The integer permission, 9 bits of this value are used.
   */
  static void set_permission(int);

  /**
   * If the user wants to allocate shared memory to use with
   * his programs, he should use the following methods to accomplish
   * this means.  These methods will provide for management of
   * the memory pages, and ensure their destruction on
   * program exit.
   *
   * Allocate memory, with a given size and return a pointer
   * to it, or 0 if no memory is available for sharing.
   *
   * @param s The size of the wanted memory block.
   * @return A pointer to allocated memory, or 0 on error.
   */
  static void *shalloc(size_t);

  /**
   * Dealloc a memory block that was allocated with the above
   * method.
   *
   * Note, that this routine will collect fragmented memory
   * into a whole segment if possible and upon receiving
   * a whole segment that has been reed, it will return it
   * back to the system and destroy its reference id.
   *
   * @param p The pointer return by the above method.
   */
  static void shdealloc(void *);

  pthread& operator= (cancel_state s) { this->set(s); return (*this); };
  pthread& operator= (cancel_type t)  { this->set(t); return (*this); };

};

#endif