Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

coherence/lang/Thread.hpp

00001 /*
00002 * Thread.hpp
00003 *
00004 * Copyright (c) 2000, 2011, 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             state_initial     = 0, // the thread has not yet started
00052             state_runnable    = 1, // the thread has started
00053             state_interrupted = 2, // the thread has been interrupted
00054             state_terminated  = 3  // the thread has completed execution
00055             } State;
00056 
00057 
00058    // ----- Maintenance definition ------------------------------------------
00059 
00060     protected:
00061         /**
00062          * Defines various thread maintenance tasks.
00063          */
00064         typedef enum
00065             {
00066             none          = 0,
00067             collect_stack = 1,
00068             compact_tls   = 2
00069             } Maintenance;
00070 
00071 
00072     // ----- constructors ---------------------------------------------------
00073 
00074     private:
00075         /**
00076         * Create a Thread.
00077         *
00078         * @param hRunnable    the Runnable to execute
00079         * @param vsName       the thread's name, or NULL for default
00080         * @param hGroup       the thread's group, or NULL for parent's
00081         * @param cBytesStack  the stack size, or 0 for default
00082         *
00083         * @return the handle to the new Thread
00084         */
00085         Thread(Runnable::Handle hRunnable,
00086                String::View vsName = String::null_string,
00087                ThreadGroup::Handle hGroup = NULL,
00088                size32_t cBytesStack = 0);
00089 
00090 
00091     // ----- Runnable interface ---------------------------------------------
00092 
00093     public:
00094         /**
00095         * {@inheritDoc}
00096         */
00097         virtual void run();
00098 
00099 
00100     // ----- Thread interface -----------------------------------------------
00101 
00102     public:
00103         /**
00104         * Return the Thread's unique ID.
00105         *
00106         * No two live thread's will have the same ID and no thread will have
00107         * an id of 0.
00108         *
00109         * @return the Thread's unique ID.
00110         */
00111         virtual int64_t getId() const;
00112 
00113         /**
00114         * Return the Thread's current state.
00115         *
00116         * @return the Thread's current state
00117         */
00118         virtual State getState() const;
00119 
00120         /**
00121         * Return the Thread's name.
00122         *
00123         * @return the Thread's name
00124         */
00125         virtual String::View getName() const;
00126 
00127         /**
00128         * Return this thread's group, or NULL if the thread has terminated.
00129         *
00130         * @return this thread's group
00131         */
00132         virtual ThreadGroup::Handle getThreadGroup();
00133 
00134         /**
00135         * Return this thread's group, or NULL if the thread has terminated.
00136         *
00137         * @return this thread's group
00138         */
00139         virtual ThreadGroup::View getThreadGroup() const;
00140 
00141         /**
00142         * Begin executing the Thread's runnable on a new system thread.
00143         *
00144         * This method may only be called once per Thread instance.
00145         *
00146         * @throw IllegalStateException if a called on a Thread which is not
00147         *        in the state state_initial.
00148         */
00149         virtual void start();
00150 
00151         /**
00152         * Request that the Thread stop executing.
00153         */
00154         virtual void interrupt();
00155 
00156         /**
00157         * Return true iff the thread is interrupted.
00158         *
00159         * @return true iff the thread is interrupted
00160         */
00161         virtual bool isInterrupted() const;
00162 
00163         /**
00164         * Wait for the Thread to reach the state_terminated state.
00165         */
00166         virtual void join() const;
00167 
00168         /**
00169         * Wait for the Thread to reach the state_terminated state.
00170         *
00171         * @param cMillis  the maximum duration to wait, or zero for infinite
00172         */
00173         virtual void join(int64_t cMillis) const;
00174 
00175         /**
00176         * Set the Thread's name.
00177         *
00178         * @param vsName  the Thread's name
00179         */
00180         virtual void setName(String::View vsName);
00181 
00182     protected:
00183         /**
00184         * Called automatically on the thread prior to termination.
00185         *
00186         * Any class extending this Thread and overriding this method much
00187         * call this implementation to ensure that join() operations complete.
00188         */
00189         virtual void onExit();
00190 
00191         /**
00192         * Instruct the thread to perform maintenance.
00193         */
00194         virtual void scheduleMaintenance(Maintenance nMaintenance) const;
00195 
00196 
00197     // ----- static helper methods ------------------------------------------
00198 
00199     public:
00200         /**
00201         * Return the Thread on which the caller is executing.
00202         *
00203         * @return the caller's thread
00204         */
00205         static Thread::Handle currentThread();
00206 
00207         /**
00208         * Return a stack trace for this thread.
00209         *
00210         * @param cTrim  the number of frames to trim from the top of the stack
00211         *
00212         * @return an array of StackTraceElements describing as much of the
00213         *         thread's stack as can be determined
00214         */
00215         static ObjectArray::Handle getStackTrace(size32_t cTrim = 0);
00216 
00217         /**
00218         * Output a stack trace to the supplied stream.
00219         *
00220         * @param out      the stream to output to
00221         * @param vaStack  the array of StackTraceElements to output, or NULL
00222         *                 for the stack of the current thread
00223         */
00224         static void outputStackTrace(std::ostream& out,
00225                 ObjectArray::View vaStack = NULL);
00226 
00227         /**
00228         * Output the stack trace of all known threads to the specified stream.
00229         *
00230         * This is a blocking operation, while the calling thread waits for
00231         * all known threads to report their stack.
00232         *
00233         * Note: This operation can also be manually triggered by sending a
00234         * SIGQUIT signal to the process. This can be done via CTRL+/ on UNIX
00235         * and CTRL+BREAK on Windows.
00236         *
00237         * @param out             the stream to output to
00238         * @param cMillisTimeout  the maximum amount of time to wait for all
00239         *                        threads to report their stacks, or -1 for
00240         *                        the system default of twice the interrupt
00241         *                        resolution
00242         */
00243         static void dumpStacks(std::ostream& out, int64_t cMillisTimeout = -1);
00244 
00245         /**
00246         * Return true iff the caller's thread has been interrupted.
00247         *
00248         * The thread's interrupt state is reset as part of this operation.
00249         *
00250         * @return true iff the caller's thread has been interrupted
00251         */
00252         static bool interrupted();
00253 
00254         /**
00255         * Pause the current thread for the specified duration.
00256         *
00257         * @param cMillis  the duration to pause the thread for.
00258         *
00259         * @throw InterruptedException if the thread is interrupted while
00260         *        sleeping.
00261         */
00262         static void sleep(int64_t cMillis);
00263 
00264         /**
00265         * Temporarily pause the current thread.
00266         */
00267         static void yield();
00268 
00269     protected:
00270         /**
00271         * Instruct all threads to perform maintenance.
00272         */
00273         static void doGlobalMaintenance(Maintenance nMaintenance);
00274 
00275 
00276     // ----- Object interface -----------------------------------------------
00277 
00278     public:
00279         /**
00280         * {@inheritDoc}
00281         *
00282         * If the associated Runnable implements the
00283         * coherence::util::Describable interface that content will be included
00284         * as well.
00285         */
00286         virtual void toStream(std::ostream &out) const;
00287 
00288 
00289     // ----- data members ---------------------------------------------------
00290 
00291     protected:
00292         /**
00293         * The thread's group.
00294         */
00295         MemberHandle<ThreadGroup> m_hGroup;
00296 
00297         /**
00298         * The inner runnable associated with this Thread.
00299         */
00300         MemberHandle<Runnable> m_hRunnable;
00301 
00302         /**
00303         * The thread's name.
00304         */
00305         MemberView<String> m_vsName;
00306 
00307         /**
00308         * The thread's description.
00309         */
00310         FinalView<String> m_vsDescription;
00311 
00312         /**
00313         * The configured stack size;
00314         */
00315         size32_t m_cBytesStack;
00316 
00317         /**
00318         * The current thread state.
00319         */
00320         Volatile<int32_t> m_nState;
00321 
00322         /**
00323         * Bit mask identifying required maintenance tasks.
00324         */
00325         mutable int m_nMaintenanceMask;
00326 
00327 
00328     // ----- friends --------------------------------------------------------
00329 
00330     friend void    coh_thread_cleanup(Thread*);
00331     friend Thread* coh_thread_current();
00332     friend class System;
00333     };
00334 
00335 COH_CLOSE_NAMESPACE2
00336 
00337 #endif // COH_THREAD_HPP
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.