thread.h

用c++包装好的线程库,直接拿来使用,提高效率.

     * @return True if the thread can be joined with.
     */
    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;
    /**
     * 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 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_e   - The process can be cancelled.
     * cancel_disable_e  - The process cannot be cancelled.
     * </pre>
     *
     * @return The cancel state.
     */
    cancel_state cancelstate() const  { return _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_e      - Cancels are deferred.
     * cancel_asynchronous_e  - Asynchronous cancels.
     * </pre>
     *
     * @return the cancel type.
     */
    cancel_type canceltype() const    { return _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 _joining = s; };
    
    /**
     * Set the cancelation state for this thread, see
     * @ref #cancelstate for a discussion on the states available.
     */
    void set(cancel_state s)          { _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)           { _canceltype = t; };
    /**
     * Set the points to jump to, on cancel or signal signals.  The
     * jump types are:
     *
     * <pre>
     * cancel_jmp_e   - When a cancel signal occurs.
     * signal_jmp_e   - On a normal signal.
     * </pre>
     *
     * @param jump the jump kind, as above.
     * @param sigjmp The jump point to set.
     */
    void set(jumps, sigjmp_buf *);
    /**
     * Tell if the signal will jump to a defined location or not.
     *
     * <pre>
     * cancel_jmp_e  - Cancel signal.
     * signal_jmp_e  _ reset signal.
     * </pre>
     *
     * @param jump the jump kind, as above.
     * @return true if a jumpbuffer is defined for the signal.
     */
    bool isSet(jumps);
    /**
     * Set any of the boolean variables this thread contains.  The
     * following are for use:
     *
     * <pre>
     * set_canceled_e       - Signify cancel state.
     * set_terminated_e     - Signify termination state.
     * set_detached_e       - Signify detached state.
     * set_exited_e         - 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();
    /**
     * Stop or suspend the process, that is running inside this
     * object.
     */
    void stop();
    /**
     * Continue, or restart a process, that is running inside this
     * object.
     */
    void resume();
    /**
     * 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(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();

    /**
     * It may come in handy, to determine the inheritance of sub
     * threads, of current attribute values for a thread.  This
     * call provides this.
     *
     * @param i Inheritance state.
     */
    void inherit(inheritance_t);

    /**
     * This is provided for the ability to reschedule a thread
     * or set its attributes according to common or user defined
     * parameters.  Be aware, that this will not merely change
     * the attributes, but will also reschedule the thread if
     * that is necessary.  It is necessary to call this routine
     * if a user wants his process to run at a higher priority,
     * or with a different policy.
     *
     */
    void schedule(attributes&);

    /**
     * A program may find it useful to determine the inheritance of
     * attributes for a given process.  By default, threads that
     * are created by a process will inherit its attributes, but
     * it may not be what the program wants or desires.  It may
     * be discovered through this call, wether this is the case
     * or not.
     *
     * @return Inheritance state of threads.
     */
    inheritance_t inherit() const;

    /** 
     * It may be useful for a a program to obtain information about
     * its scope.  The thread itself, does not use this attribute
     * on its own, but it can be used in determining the value
     * of mutex, semaphore and cond variable classes inside the
     * program.
     *
     * @return The scope of the thread.
     */
    scope_t scope() const;

    /**
     * Scheduling policy of a thread, may also be useful in obtaining
     * by a program.  Although this can easily be obtained through the
     * kernel scheduler, this may prove to be a less expensive means
     * for a program to obtain the information by.
     *
     * @return Scheduling, as defined in attribute setting.
     */
    policy_t policy() const;

    /**
     * Return the base of the stack.
     *
     * @return Stack base.
     */
    ThreadStack *stack();

    /**
     * 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 setProject(const std::string&);
    
    /**
     * 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 setPermission(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 read, 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 *);
    
    /**
     * Return a reference to the main program thread.
     *
     * This allows a program, to have some control over the
     * main program behaviour, within a threaded environment.
     */
    static Pthread *_main();
    /**
     * Return the reference to the thread associated with the
     * caller.
     */
    static Pthread *self();
    /**
     * Return the reference to the thread, given by the process
     * id passed.
     *
     * @param pid The process id of the thread to obtain.
     */
    static Pthread *ptr(int);
    /**
     * Print a debug message, that is global to all threads.
     *
     * @param f A formatted message, ala printf.
     */
    static void debug(const char *,...);

    /**
     * Obtain the attributes of this thread.
     */
    operator attributes();

    /**
     * Query wether the thread is running.
     */
    operator bool();

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

}; // Namespace

#endif