mitsuba/include/mitsuba/core/thread.h

/*
    This file is part of Mitsuba, a physically based rendering system.

    Copyright (c) 2007-2014 by Wenzel Jakob and others.

    Mitsuba is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License Version 3
    as published by the Free Software Foundation.

    Mitsuba is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program. If not, see <http://www.gnu.org/licenses/>.
*/

#pragma once
#if !defined(__MITSUBA_CORE_THREAD_H_)
#define __MITSUBA_CORE_THREAD_H_

#include <mitsuba/mitsuba.h>
#include <boost/scoped_ptr.hpp>

MTS_NAMESPACE_BEGIN

/**
 * \headerfile mitsuba/core/thread.h mitsuba/mitsuba.h
 * \brief Cross-platform thread implementation
 * \ingroup libcore
 * \ingroup libpython
 */
class MTS_EXPORT_CORE Thread : public Object {
public:
	/// Possible priority values for \ref Thread::setPriority()
	enum EThreadPriority {
		EIdlePriority = 0,
		ELowestPriority,
		ELowPriority,
		ENormalPriority,
		EHighPriority,
		EHighestPriority,
		ERealtimePriority
	};

	/**
	 * \brief Create a new thread object
	 * \param name An identifying name of this thread
	 *   (will be shown in debug messages)
	 * \remark Note that it is currently not possible to
	 *         construct Thread instances from Python
	 */
	Thread(const std::string &name);

	/**
	 * \brief Set the thread priority
	 *
	 * This does not always work -- for instance, Linux
	 * requires root privileges for this operation.
	 *
	 * \return \c true upon success.
	 */
	bool setPriority(EThreadPriority priority);

	/// Return the thread priority
	EThreadPriority getPriority() const;

	/**
	 * \brief Set the core affinity
	 *
	 * This function provides a hint to the operating system
	 * scheduler that the thread should preferably run
	 * on the specified processor core. By default, the parameter
	 * is set to -1, which means that there is no affinity.
	 */
	void setCoreAffinity(int core);

	/// Return the core affinity
	int getCoreAffinity() const;

	/**
	 * \brief Specify whether or not this thread is critical
	 *
	 * When an thread marked critical crashes from an uncaught
	 * exception, the whole process is brought down.
	 * The default is \c false.
	 */
	void setCritical(bool critical);

	/// Return the value of the critical flag
	bool getCritical() const;

	/// Return the thread ID
	static int getID();

	/// Return the name of this thread
	const std::string &getName() const;

	/// Set the name of this thread
	void setName(const std::string &name);

	/// Return the parent thread
	Thread *getParent();

	/// Return the parent thread (const version)
	const Thread *getParent() const;

	/// Set the logger instance used to process log messages from this thread
	void setLogger(Logger *logger);

	/// Return the thread's logger instance
	Logger *getLogger();

	/// Set the thread's file resolver
	void setFileResolver(FileResolver *fresolver);

	/// Return the thread's file resolver
	FileResolver *getFileResolver();

	/// Return the current thread
	static Thread *getThread();

	/// Is this thread still running?
	bool isRunning() const;

	/// Start the thread
	void start();

	/**
	 * \brief Detach the thread and release resources
	 *
	 * After a call to this function, \ref join()
	 * cannot be used anymore. This releases resources, which
	 * would otherwise be held until a call to \ref join().
	 */
	void detach();

	/// Wait until the thread finishes
	void join();

	/// Return a string representation
	virtual std::string toString() const;

	/// Sleep for a certain amount of time
	static void sleep(unsigned int ms);

	/// Initialize the threading system
	static void staticInitialization();

	/// Shut down the threading system
	static void staticShutdown();

	/// Initialize Mitsuba's threading system for simultaneous use of OpenMP
	static void initializeOpenMP(size_t threadCount);

	/**
	 * \brief Register an unmanaged thread with Mitsuba (i.e. one that
	 * doesn't derive from \c mitsuba::Thread)
	 *
	 * Should be called from the thread in question. The function returns
	 * a Mitsuba handle to the thread
	 */
	static Thread *registerUnmanagedThread(const std::string &name);

	/**
	 * \brief Register a thread crash handler
	 *
	 * A crash handler is called whenever a thread fails with an uncaught
	 * exception. This can be used to implement more useful error messages
	 * in certain circumstances
	 */
	static void registerCrashHandler(bool (*handler)(void));

	MTS_DECLARE_CLASS()
protected:
	/// Virtual destructor
	virtual ~Thread();

	/// Thread dispatch function
	static void dispatch(Thread *thread);

	/**
	 * Exit the thread, should be called from
	 * inside the thread
	 */
	void exit();

	/// Yield to another processor
	void yield();

	/// The thread's run method
	virtual void run() = 0;
private:
	struct ThreadPrivate;
	boost::scoped_ptr<ThreadPrivate> d;
};

#if defined(MTS_OPENMP)
#if defined(__OSX__)
/// Variant of \c omp_get_max_threads that works on OSX
extern MTS_EXPORT_CORE int mts_omp_get_max_threads();

/// Variant of \c omp_get_thread_num that works on OSX
extern MTS_EXPORT_CORE int mts_omp_get_thread_num();
#else
#define mts_omp_get_max_threads omp_get_max_threads
#define mts_omp_get_thread_num omp_get_thread_num
#endif
#else
#define mts_omp_get_max_threads() 1
#define mts_omp_get_thread_num() 0
#endif

MTS_NAMESPACE_END

#endif /* __MITSUBA_CORE_THREAD_H_ */