coherence/lang/Thread.hpp

/*
* Thread.hpp
*
* Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_THREAD_HPP
#define COH_THREAD_HPP

#include "coherence/lang/compatibility.hpp"

#include "coherence/lang/FinalHandle.hpp"
#include "coherence/lang/FinalView.hpp"
#include "coherence/lang/Object.hpp"
#include "coherence/lang/ObjectArray.hpp"
#include "coherence/lang/MemberView.hpp"
#include "coherence/lang/Runnable.hpp"
#include "coherence/lang/String.hpp"
#include "coherence/lang/TypedHandle.hpp"
#include "coherence/lang/Volatile.hpp"

COH_OPEN_NAMESPACE2(coherence,lang)


/**
* An Object representing a thread of execution.
*
* @author mf 2007.12.10
*/
class COH_EXPORT Thread
    : public class_spec<Thread,
        extends<Object>,
        implements<Runnable> >
    {
    friend class factory<Thread>;

    // ----- State definition -----------------------------------------------

    public:
        typedef enum
            {
            NEW         = 0, // the thread has not yet started
            RUNNABLE    = 1, // the thread has started
            INTERRUPTED = 2, // the thread has been interrupted
            TERMINATED  = 3  // the thread has completed execution
            } State;


    // ----- constructors ---------------------------------------------------

    private:
        /**
        * Create a Thread.
        *
        * @param hRunnable    the Runnable to execute
        * @param vsName       the thread's name, or NULL for default
        * @param cBytesStack  the stack size or 0 for default
        *
        * @return the handle to the new Thread
        */
        Thread(Runnable::Handle hRunnable,
                String::View vsName = String::NULL_STRING,
                size32_t cBytesStack = 0);


    // ----- Runnable interface ---------------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual void run();


    // ----- Thread interface -----------------------------------------------

    public:
        /**
        * Return the Thread's unique ID.
        *
        * No two live thread's will have the same ID and no thread will have
        * an id of 0.
        *
        * @return the Thread's unique ID.
        */
        virtual int64_t getId() const;

        /**
        * Return the Thread's current state.
        *
        * @return the Thread's current state
        */
        virtual State getState() const;

        /**
        * Return the Thread's name.
        *
        * @return the Thread's name
        */
        virtual String::View getName() const;

        /**
        * Begin executing the Thread's runnable on a new system thread.
        *
        * This method may only be called once per Thread instance.
        *
        * @throw IllegalStateException if a called on a Thread which is not
        *        in the state NEW.
        */
        virtual void start();

        /**
        * Request that the Thread stop executing.
        */
        virtual void interrupt();

        /**
        * Return true iff the thread is interrupted.
        *
        * @return true iff the thread is interrupted
        */
        virtual bool isInterrupted() const;

        /**
        * Wait for the Thread to reach the TERMINATED state.
        */
        virtual void join() const;

        /**
        * Wait for the Thread to reach the TERMINATED state.
        *
        * @param cMillis  the maximum duration to wait, or zero for infinite
        */
        virtual void join(int64_t cMillis) const;

        /**
        * Set the Thread's name.
        *
        * @param vsName  the Thread's name
        */
        virtual void setName(String::View vsName);

    protected:
        /**
        * Called automatically on the thread prior to termination.
        *
        * Any class extending this Thread and overriding this method much
        * call this implementation to ensure that join() operations complete.
        */
        virtual void onExit();

        /**
        * Instruct the thread to collect its stack.
        */
        virtual void collectStackTrace() const;


    // ----- static helper methods ------------------------------------------

    public:
        /**
        * Return the Thread on which the caller is executing.
        *
        * @return the caller's thread
        */
        static Thread::Handle currentThread();

        /**
        * Return an array of all known threads.
        *
        * @return an array of Thread views.
        */
        static ObjectArray enumerate();

        /**
        * Return a stack trace for this thread.
        *
        * @param cTrim  the number of frames to trim from the top of the stack
        *
        * @return an array of StackTraceElements describing as much of the
        *         thread's stack as can be determined
        */
        static ObjectArray::Handle getStackTrace(size32_t cTrim = 0);

        /**
        * Output a stack trace to the supplied stream.
        *
        * @param out      the stream to output to
        * @param vaStack  the array of StackTraceElements to output, or NULL
        *                 for the stack of the current thread
        */
        static void outputStackTrace(std::ostream& out,
                ObjectArray::View vaStack = NULL);

        /**
        * Output the stack trace of all known threads to the specified stream.
        *
        * This is a blocking operation, while the calling thread waits for
        * all known threads to report their stack.
        *
        * Note: This operation can also be manually triggered by sending a
        * SIGQUIT signal to the process. This can be done via CTRL+/ on UNIX
        * and CTRL+BREAK on Windows.
        *
        * @param out             the stream to output to
        * @param cMillisTimeout  the maximum amount of time to wait for all
        *                        threads to report their stacks, or -1 for
        *                        the system default of twice the interrupt
        *                        resolution
        */
        static void dumpStacks(std::ostream& out, int64_t cMillisTimeout = -1);

        /**
        * Return true iff the caller's thread has been interrupted.
        *
        * The thread's interrupt state is reset as part of this operation.
        *
        * @return true iff the caller's thread has been interrupted
        */
        static bool interrupted();

        /**
        * Pause the current thread for the specified duration.
        *
        * @param cMillis  the duration to pause the thread for.
        *
        * @throw InterruptedException if the thread is interrupted while
        *        sleeping.
        */
        static void sleep(int64_t cMillis);

        /**
        * Temporarily pause the current thread.
        */
        static void yield();


    // ----- Object interface -----------------------------------------------

    public:
        /**
        * {@inheritDoc}
        *
        * If the associated Runnable implements the
        * coherence::util::Describable interface that content will be included
        * as well.
        */
        virtual void toStream(std::ostream &out) const;


    // ----- data members ---------------------------------------------------

    protected:
        /**
        * The inner runnable associated with this Thread.
        */
        MemberHandle<Runnable> m_hRunnable;

        /**
        * The thread's name.
        */
        MemberView<String> m_vsName;

        /**
        * The thread's description.
        */
        FinalView<String> m_vsDescription;

        /**
        * The configured stack size;
        */
        size32_t m_cBytesStack;

        /**
        * The current thread state.
        */
        Volatile<int32_t> m_nState;

        /**
        * True if a request has been made for a stack dump.
        */
        mutable bool m_fCollectStack;


    // ----- friends --------------------------------------------------------

    friend void    coh_thread_cleanup(Thread*);
    friend Thread* coh_thread_current();
    };

COH_CLOSE_NAMESPACE2

#endif // COH_THREAD_HPP

Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.