Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/lang/Thread.hpp

00001 /*
00002 * Thread.hpp
00003 *
00004 * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
00005 *
00006 * Oracle is a registered trademarks of Oracle Corporation and/or its
00007 * affiliates.
00008 *
00009 * This software is the confidential and proprietary information of Oracle
00010 * Corporation. You shall not disclose such confidential and proprietary
00011 * information and shall use it only in accordance with the terms of the
00012 * license agreement you entered into with Oracle.
00013 *
00014 * This notice may not be removed or altered.
00015 */
00016 #ifndef COH_THREAD_HPP
00017 #define COH_THREAD_HPP
00018 
00019 #include "coherence/lang/compatibility.hpp"
00020 
00021 #include "coherence/lang/FinalHandle.hpp"
00022 #include "coherence/lang/FinalView.hpp"
00023 #include "coherence/lang/Object.hpp"
00024 #include "coherence/lang/ObjectArray.hpp"
00025 #include "coherence/lang/MemberView.hpp"
00026 #include "coherence/lang/Runnable.hpp"
00027 #include "coherence/lang/String.hpp"
00028 #include "coherence/lang/ThreadGroup.hpp"
00029 #include "coherence/lang/TypedHandle.hpp"
00030 #include "coherence/lang/Volatile.hpp"
00031 
00032 COH_OPEN_NAMESPACE2(coherence,lang)
00033 
00034 /**
00035 * An Object representing a thread of execution.
00036 *
00037 * @author mf 2007.12.10
00038 */
00039 class COH_EXPORT Thread
00040     : public class_spec<Thread,
00041         extends<Object>,
00042         implements<Runnable> >
00043     {
00044     friend class factory<Thread>;
00045 
00046     // ----- State definition -----------------------------------------------
00047 
00048     public:
00049         typedef enum
00050             {
00051             NEW         = 0, // the thread has not yet started
00052             RUNNABLE    = 1, // the thread has started
00053             INTERRUPTED = 2, // the thread has been interrupted
00054             TERMINATED  = 3  // the thread has completed execution
00055             } State;
00056 
00057 
00058     // ----- constructors ---------------------------------------------------
00059 
00060     private:
00061         /**
00062         * Create a Thread.
00063         *
00064         * @param hRunnable    the Runnable to execute
00065         * @param vsName       the thread's name, or NULL for default
00066         * @param hGroup       the thread's group, or NULL for parent's
00067         * @param cBytesStack  the stack size, or 0 for default
00068         *
00069         * @return the handle to the new Thread
00070         */
00071         Thread(Runnable::Handle hRunnable,
00072                String::View vsName = String::NULL_STRING,
00073                ThreadGroup::Handle hGroup = NULL,
00074                size32_t cBytesStack = 0);
00075 
00076 
00077     // ----- Runnable interface ---------------------------------------------
00078 
00079     public:
00080         /**
00081         * {@inheritDoc}
00082         */
00083         virtual void run();
00084 
00085 
00086     // ----- Thread interface -----------------------------------------------
00087 
00088     public:
00089         /**
00090         * Return the Thread's unique ID.
00091         *
00092         * No two live thread's will have the same ID and no thread will have
00093         * an id of 0.
00094         *
00095         * @return the Thread's unique ID.
00096         */
00097         virtual int64_t getId() const;
00098 
00099         /**
00100         * Return the Thread's current state.
00101         *
00102         * @return the Thread's current state
00103         */
00104         virtual State getState() const;
00105 
00106         /**
00107         * Return the Thread's name.
00108         *
00109         * @return the Thread's name
00110         */
00111         virtual String::View getName() const;
00112 
00113         /**
00114         * Return this thread's group, or NULL if the thread has terminated.
00115         *
00116         * @return this thread's group
00117         */
00118         virtual ThreadGroup::Handle getThreadGroup();
00119 
00120         /**
00121         * Return this thread's group, or NULL if the thread has terminated.
00122         *
00123         * @return this thread's group
00124         */
00125         virtual ThreadGroup::View getThreadGroup() const;
00126 
00127         /**
00128         * Begin executing the Thread's runnable on a new system thread.
00129         *
00130         * This method may only be called once per Thread instance.
00131         *
00132         * @throw IllegalStateException if a called on a Thread which is not
00133         *        in the state NEW.
00134         */
00135         virtual void start();
00136 
00137         /**
00138         * Request that the Thread stop executing.
00139         */
00140         virtual void interrupt();
00141 
00142         /**
00143         * Return true iff the thread is interrupted.
00144         *
00145         * @return true iff the thread is interrupted
00146         */
00147         virtual bool isInterrupted() const;
00148 
00149         /**
00150         * Wait for the Thread to reach the TERMINATED state.
00151         */
00152         virtual void join() const;
00153 
00154         /**
00155         * Wait for the Thread to reach the TERMINATED state.
00156         *
00157         * @param cMillis  the maximum duration to wait, or zero for infinite
00158         */
00159         virtual void join(int64_t cMillis) const;
00160 
00161         /**
00162         * Set the Thread's name.
00163         *
00164         * @param vsName  the Thread's name
00165         */
00166         virtual void setName(String::View vsName);
00167 
00168     protected:
00169         /**
00170         * Called automatically on the thread prior to termination.
00171         *
00172         * Any class extending this Thread and overriding this method much
00173         * call this implementation to ensure that join() operations complete.
00174         */
00175         virtual void onExit();
00176 
00177         /**
00178         * Instruct the thread to collect its stack.
00179         */
00180         virtual void collectStackTrace() const;
00181 
00182 
00183     // ----- static helper methods ------------------------------------------
00184 
00185     public:
00186         /**
00187         * Return the Thread on which the caller is executing.
00188         *
00189         * @return the caller's thread
00190         */
00191         static Thread::Handle currentThread();
00192 
00193         /**
00194         * Return a stack trace for this thread.
00195         *
00196         * @param cTrim  the number of frames to trim from the top of the stack
00197         *
00198         * @return an array of StackTraceElements describing as much of the
00199         *         thread's stack as can be determined
00200         */
00201         static ObjectArray::Handle getStackTrace(size32_t cTrim = 0);
00202 
00203         /**
00204         * Output a stack trace to the supplied stream.
00205         *
00206         * @param out      the stream to output to
00207         * @param vaStack  the array of StackTraceElements to output, or NULL
00208         *                 for the stack of the current thread
00209         */
00210         static void outputStackTrace(std::ostream& out,
00211                 ObjectArray::View vaStack = NULL);
00212 
00213         /**
00214         * Output the stack trace of all known threads to the specified stream.
00215         *
00216         * This is a blocking operation, while the calling thread waits for
00217         * all known threads to report their stack.
00218         *
00219         * Note: This operation can also be manually triggered by sending a
00220         * SIGQUIT signal to the process. This can be done via CTRL+/ on UNIX
00221         * and CTRL+BREAK on Windows.
00222         *
00223         * @param out             the stream to output to
00224         * @param cMillisTimeout  the maximum amount of time to wait for all
00225         *                        threads to report their stacks, or -1 for
00226         *                        the system default of twice the interrupt
00227         *                        resolution
00228         */
00229         static void dumpStacks(std::ostream& out, int64_t cMillisTimeout = -1);
00230 
00231         /**
00232         * Return true iff the caller's thread has been interrupted.
00233         *
00234         * The thread's interrupt state is reset as part of this operation.
00235         *
00236         * @return true iff the caller's thread has been interrupted
00237         */
00238         static bool interrupted();
00239 
00240         /**
00241         * Pause the current thread for the specified duration.
00242         *
00243         * @param cMillis  the duration to pause the thread for.
00244         *
00245         * @throw InterruptedException if the thread is interrupted while
00246         *        sleeping.
00247         */
00248         static void sleep(int64_t cMillis);
00249 
00250         /**
00251         * Temporarily pause the current thread.
00252         */
00253         static void yield();
00254 
00255 
00256     // ----- Object interface -----------------------------------------------
00257 
00258     public:
00259         /**
00260         * {@inheritDoc}
00261         *
00262         * If the associated Runnable implements the
00263         * coherence::util::Describable interface that content will be included
00264         * as well.
00265         */
00266         virtual void toStream(std::ostream &out) const;
00267 
00268 
00269     // ----- data members ---------------------------------------------------
00270 
00271     protected:
00272         /**
00273         * The thread's group.
00274         */
00275         MemberHandle<ThreadGroup> m_hGroup;
00276 
00277         /**
00278         * The inner runnable associated with this Thread.
00279         */
00280         MemberHandle<Runnable> m_hRunnable;
00281 
00282         /**
00283         * The thread's name.
00284         */
00285         MemberView<String> m_vsName;
00286 
00287         /**
00288         * The thread's description.
00289         */
00290         FinalView<String> m_vsDescription;
00291 
00292         /**
00293         * The configured stack size;
00294         */
00295         size32_t m_cBytesStack;
00296 
00297         /**
00298         * The current thread state.
00299         */
00300         Volatile<int32_t> m_nState;
00301 
00302         /**
00303         * True if a request has been made for a stack dump.
00304         */
00305         mutable bool m_fCollectStack;
00306 
00307 
00308     // ----- friends --------------------------------------------------------
00309 
00310     friend void    coh_thread_cleanup(Thread*);
00311     friend Thread* coh_thread_current();
00312     };
00313 
00314 COH_CLOSE_NAMESPACE2
00315 
00316 #endif // COH_THREAD_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.