/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#ifndef _DECAF_LANG_THREAD_H_
#define _DECAF_LANG_THREAD_H_

#include <decaf/lang/exceptions/IllegalThreadStateException.h>
#include <decaf/lang/exceptions/IllegalArgumentException.h>
#include <decaf/lang/exceptions/InterruptedException.h>
#include <decaf/lang/exceptions/RuntimeException.h>
#include <decaf/lang/Exception.h>
#include <decaf/lang/Runnable.h>
#include <decaf/util/Config.h>

namespace decaf {
namespace internal {
namespace util {
namespace concurrent {
    class Threading;
    struct ThreadHandle;
}}}
namespace lang {

    class ThreadGroup;
    class ThreadProperties;

    /**
     * A Thread is a concurrent unit of execution. It has its own call stack for
     * methods being invoked, their arguments and local variables. Each process has at
     * least one main Thread running when it is started; typically, there are
     * several others for housekeeping. The application might decide to launch additional
     * Threads for specific purposes.
     *
     * Threads in the same process interact and synchronize by the use of shared
     * objects and monitors associated with these objects.
     *
     * There are basically two main ways of having a Thread execute application
     * code. One is providing a new class that extends Thread and overriding
     * its {@link #run()} method. The other is providing a new Thread instance
     * with a {@link Runnable} object during its creation. In both cases, the
     * {@link #start()} method must be called to actually execute the new Thread.
     *
     * Each Thread has an integer priority that basically determines the amount
     * of CPU time the Thread gets. It can be set using the {@link #setPriority(int)}
     * method.
     *
     * @see decaf.lang.ThreadGroup
     *
     * @since 1.0
     */
    class DECAF_API Thread : public Runnable {
    private:

        /**
         * The internal data necessary to manage a Thread instance.
         */
        ThreadProperties* properties;

    public:

        /** The minimum priority that a thread can have. */
        static const int MIN_PRIORITY = 1;

        /** The default priority that a thread is given at create time. */
        static const int NORM_PRIORITY = 5;

        /** The maximum priority that a thread can have. */
        static const int MAX_PRIORITY = 10;

        /** Represents the various states that the Thread can be in during its lifetime. */
        enum State {

            /** Before a Thread is started it exists in this State. */
            NEW = 0,

            /** While a Thread is running and is not blocked it is in this State. */
            RUNNABLE = 1,

            /** A Thread that is waiting to acquire a lock is in this state. */
            BLOCKED = 2,

            /** A Thread that is waiting for another Thread to perform an action is in this state */
            WAITING = 3,

            /**
             * A Thread that is waiting for another Thread to perform an action up to a specified
             * time interval is in this state.
             */
            TIMED_WAITING = 4,

            /** A Thread that is blocked in a Sleep call is in this state. */
            SLEEPING = 5,

            /** A Thread whose run method has exited is in this state. */
            TERMINATED = 6

        };

    public:

        /**
         * Interface for handlers invoked when a Thread abruptly terminates due to an
         * uncaught exception.
         */
        class UncaughtExceptionHandler {
        public:

            virtual ~UncaughtExceptionHandler() {}

            /**
             * Method invoked when the given thread terminates due to the given uncaught exception.
             *
             * This method is defined to indicate that it will not throw an exception, throwing
             * and exception from this method will on most systems result in a segmentation fault.
             */
            virtual void uncaughtException(const Thread* thread, const Throwable& error) = 0;

        };

    private:

        Thread(const Thread&);
        Thread& operator=(const Thread&);

    public:

        /**
         * Constructs a new Thread. This constructor has the same effect as
         * Thread( NULL, NULL, GIVEN_NAME ), where GIVEN_NAME is a newly generated name.
         * When no name is given the name is automatically generated and are of the form
         * "Thread-"+n, where n is an integer.
         */
        Thread();

        /**
         * Constructs a new Thread with the given target Runnable task. This constructor
         * has the same effect as Thread( NULL, task, GIVEN_NAME ), where GIVEN_NAME is a
         * newly generated name.  When no name is given the name is automatically generated
         * and are of the form  "Thread-"+n, where n is an integer.
         *
         * @param task the Runnable that this thread manages, if the task is NULL the Thread's
         *        run method is used instead.
         */
        Thread(Runnable* task);

        /**
         * Constructs a new Thread with the given name. This constructor has the same effect
         * as Thread( NULL, NULL, GIVEN_NAME ), where GIVEN_NAME is a newly generated name.
         * When no name is given the name is automatically generated and are of the form
         * "Thread-"+n, where n is an integer.
         *
         * @param name the name to assign to this Thread.
         */
        Thread(const std::string& name);

        /**
         * Constructs a new Thread with the given target Runnable task and name. This constructor
         * has the same effect as Thread( NULL, task, GIVEN_NAME ), where GIVEN_NAME is a
         * newly generated name.  When no name is given the name is automatically generated
         * and are of the form  "Thread-"+n, where n is an integer.
         *
         * @param task the Runnable that this thread manages, if the task is NULL the Thread's
         *        run method is used instead.
         * @param name the name to assign to this Thread.
         */
        Thread(Runnable* task, const std::string& name);

        /**
         * Constructs a new Thread with the given target Runnable task and name. This constructor
         * has the same effect as Thread( NULL, task, GIVEN_NAME ), where GIVEN_NAME is a
         * newly generated name.  When no name is given the name is automatically generated
         * and are of the form  "Thread-"+n, where n is an integer.
         *
         * The stack size option is platform independent and may have no effect on the newly
         * created thread on some systems.  If the value given is invalid on the system a
         * RuntimeException is thrown, the stack size can be invalid if it is outside the
         * allowed range or doesn't match the size of the system page size on some system.
         *
         * @param task
         *      The Runnable that this thread manages, if the task is NULL the Thread's
         *      run method is used instead.
         * @param name
         *      The name to assign to this Thread.
         * @param stackSize
         *      The size of the newly allocated thread's stack.
         */
        Thread(Runnable* task, const std::string& name, long long stackSize);

        virtual ~Thread();

        /**
         * Creates a system thread and starts it in a joinable mode.  Upon creation, the
         * run() method of either this object or the provided Runnable object will be
         * invoked in the context of this thread.
         *
         * @throws IllegalThreadStateException if the thread has already been started.
         * @throws RuntimeException if the Thread cannot be created for some reason.
         */
        virtual void start();

        /**
         * Forces the Current Thread to wait until the thread exits.
         *
         * @throws InterruptedException if any thread has interrupted the current thread.
         *         The interrupted status of the current thread is cleared when this
         *         exception is thrown.
         */
        virtual void join();

        /**
         * Forces the Current Thread to wait until the thread exits.
         *
         * @param millisecs the time in Milliseconds before the thread resumes
         *
         * @throws IllegalArgumentException if the milliseconds parameter is negative.
         * @throws InterruptedException if any thread has interrupted the current thread.
         *         The interrupted status of the current thread is cleared when this
         *         exception is thrown.
         */
        virtual void join(long long millisecs);

        /**
         * Forces the Current Thread to wait until the thread exits.
         *
         * @param millisecs the time in Milliseconds before the thread resumes
         * @param nanos 0-999999 extra nanoseconds to sleep.
         *
         * @throws IllegalArgumentException if the nanoseconds parameter is out of range
         *         or the milliseconds paramter is negative.
         * @throws InterruptedException if any thread has interrupted the current thread.
         *         The interrupted status of the current thread is cleared when this
         *         exception is thrown.
         */
        virtual void join(long long millisecs, int nanos);

        /**
         * Default implementation of the run method - does nothing.
         */
        virtual void run();

        /**
         * Obtains the Thread Id of the current thread, this value is OS specific but is
         * guaranteed not to change for the lifetime of this thread.
         *
         * @return Thread Id of this Thread instance.
         */
        long long getId() const;

        /**
         * Returns the Thread's assigned name.
         * @return the Name of the Thread.
         */
        std::string getName() const;

        /**
         * Sets the name of the Thread to the new Name given by the argument <em>name</em>
         *
         * @paran name the new name of the Thread.
         */
        void setName(const std::string& name);

        /**
         * Gets the currently set priority for this Thread.
         *
         * @return an int value representing the Thread's current priority.
         */
        int getPriority() const;

        /**
         * Sets the current Thread's priority to the newly specified value.  The given value
         * must be within the range Thread::MIN_PRIORITY and Thread::MAX_PRIORITY.
         *
         * @param value the new priority value to assign to this Thread.
         *
         * @throws IllegalArgumentException if the value is out of range.
         */
        void setPriority(int value);

        /**
         * Set the handler invoked when this thread abruptly terminates due to an uncaught exception.
         *
         * @return a pointer to the set UncaughtExceptionHandler.
         */
        UncaughtExceptionHandler* getUncaughtExceptionHandler() const;

        /**
         * Set the handler invoked when this thread abruptly terminates due to an uncaught exception.
         *
         * @param handler the UncaightExceptionHandler to invoke when the Thread terminates due
         *                to an uncaught exception.
         */
        void setUncaughtExceptionHandler(UncaughtExceptionHandler* handler);

        /**
         * Returns a string that describes the Thread.
         *
         * @return string describing the Thread.
         */
        std::string toString() const;

        /**
         * Returns true if the Thread is alive, meaning it has been started and has not yet
         * died.
         *
         * @return true if the thread is alive.
         */
        bool isAlive() const;

        /**
         * Returns the currently set State of this Thread.
         *
         * @return the Thread's current state.
         */
        Thread::State getState() const;

        /**
         * Interrupts the Thread if it is blocked and in an interruptible state.
         *
         * When the thread is in one of its own join or sleep methods or blocked by a call to
         * a monitor or mutex wait call it will clear its interrupted flag and and an
         * InterruptedException will be thrown.
         *
         * In other cases the thread's interrupted status will be set and an instance of
         * an InterruptedException may be thrown.
         *
         * If the thread is not alive when this method is called there is no affect.
         */
        void interrupt();

        /**
         * Returns but does not clear the state of this Thread's interrupted flag.
         *
         * @return true if the thread was interrupted, false otherwise.
         */
        bool isInterrupted() const;

    public:

        /**
         * Causes the currently executing thread to halt execution for the specified number of
         * milliseconds, subject to the precision and accuracy of system timers and schedulers.
         *
         * Note that this method is a static method that applies to the
         * calling thread and not to the thread object.
         *
         * @param millisecs time in milliseconds to halt execution.
         *
         * @throws IllegalArgumentException if the milliseconds parameter is negative.
         * @throws InterruptedException if the Thread was interrupted while sleeping.
         */
        static void sleep(long long millisecs);

        /**
         * Causes the currently executing thread to halt execution for the specified number of
         * milliseconds plus any additionally specified nanoseconds given, subject to the precision
         * and accuracy of system timers and schedulers.
         *
         * Note that this method is a static method that applies to the
         * calling thread and not to the thread object.
         *
         * @param millisecs time in milliseconds to halt execution.
         * @param nanos 0-999999 extra nanoseconds to sleep.
         *
         * @throws IllegalArgumentException if the nanoseconds parameter is out of range
         *         or the milliseconds paramter is negative.
         * @throws InterruptedException if the Thread was interrupted while sleeping.
         */
        static void sleep(long long millisecs, int nanos);

        /**
         * Causes the currently executing thread object to temporarily pause
         * and allow other threads to execute.
         */
        static void yield();

        /**
         * Returns a pointer to the currently executing thread object.
         *
         * @return Pointer to the Thread object representing the currently running Thread.
         */
        static Thread* currentThread();

        /**
         * Returns whether the thread has been interrupted and clears the interrupted state
         * such that a subsequent call will return false unless an interrupt occurs between
         * the two calls.
         *
         * @return true if the thread was interrupted, false otherwise.
         */
        static bool interrupted();

        /**
         * Set the default handler invoked when a thread abruptly terminates due to an uncaught
         * exception, this handler is used only if there is no other handler defined for the
         * Thread.  This method will return NULL if no handler has ever been set, or the handler
         * is cleared via a call to the setDefaultUncaughtExceptionHandler method will NULL as
         * the value of the handler argument.
         *
         * @return a pointer to the default UncaughtExceptionHandler for all Threads.
         */
        static UncaughtExceptionHandler* getDefaultUncaughtExceptionHandler();

        /**
         * Set the default handler invoked when a thread abruptly terminates due to an uncaught
         * exception,
         *
         * @param handler
         *      The UncaightExceptionHandler to invoke when a Thread terminates due
         *      to an uncaught exception, passing NULL clears this value.
         */
        static void setDefaultUncaughtExceptionHandler(UncaughtExceptionHandler* handler);

    private:

        // Initialize the Threads internal state
        void initializeSelf(Runnable* task, const std::string& name, long long stackSize);

        // Creates a Thread instance for a ThreadProperties pointer, used for
        // wrapping OS threads
        Thread(decaf::internal::util::concurrent::ThreadHandle* osThread);

    private:

        // Allows the Threading class to get this thread objects handle.
        decaf::internal::util::concurrent::ThreadHandle* getHandle() const;

        // Allow some Decaf Classes greater access to the Thread class.
        friend class decaf::internal::util::concurrent::Threading;
        friend class ThreadGroup;

    };

}}

#endif /*_DECAF_LANG_THREAD_H_*/