Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

# 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.