vm/port/include/port_thread.h - harmony-drlvm - Git at Google

 /*
  *  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 _PORT_THREAD_H_
 #define _PORT_THREAD_H_

 /**
  * @file port_thread.h
  * @brief PORT thread support
  */

 /* osthread_t and thread_context_t types, and proper windows.h inclusion */
 #include "open/hythread_ext.h"

 #include "port_general.h"

 /* Thread context definition for UNIX-like systems */
 #if defined(LINUX) || defined(FREEBSD)
 #if defined(LINUX)

 #include <sys/types.h>
 #include <linux/unistd.h>
 #include <errno.h>

 #ifdef _syscall0
 static _syscall0(pid_t, gettid)/* static definition */
 #else /* _syscall0 */
 #include <sys/syscall.h>
 #include <unistd.h>
 #define gettid() ((pid_t)syscall(__NR_gettid))
 #endif /* _syscall0 */

 #else /* !LINUX */
 #include <sys/types.h>
 #include <unistd.h>
 #define gettid() getpid()
 #endif

 #endif /* LINUX || FREEBSD */


 /* To skip platform_types.h inclusion */
 typedef struct Registers Registers;

 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */


 /** @name OS thread operations
  */
 //@{

 PORT_INLINE int port_gettid()
 {
 #ifdef PLATFORM_POSIX
     return gettid();
 #else
     return (int)GetCurrentThreadId();
 #endif
 }

 /**
  * The type of pointer to thread start function
  * Function receives single argument - user-defined pointer
  */
 typedef int (PORT_CDECL *port_threadfunc_t)(void*);

 /**
  * Creates new thread.
  *
  * @param[out] handle on success, thread handle is stored in memory pointed by handle
  * @param stacksize size of stack to be allocated for a new thread
  * @param priority priority of a new thread
  * @param func function to be started on a new thread
  * @param data value to be passed to a function started on a new thread
  *
  * @return 0 on success, system error otherwise.
  */
 int port_thread_create(osthread_t* phandle, size_t stacksize, int priority,
         port_threadfunc_t func, void *data);

 /**
  * Attaches current thread to the porting library.
  *
  * This includes setting guard page in thread's stack memory and setting
  * alternative stack for stack overflow processing.
  * This function should be called for any thread which can produce expected
  * hardware signals/exceptions, to guarantee proper signals processing.
  *
  * @return 0 on success, system error otherwise.
  *
  * @sa port_thread_detach()
  */
 int port_thread_attach();

 /**
  * Detaches current thread from the porting library.
  * This includes restoring thread's stack settings.
  *
  * @return 0 on success, system error otherwise.
  *
  * @sa port_thread_attach()
  */
 int port_thread_detach();

 /**
  * Restores guard page after stack overflow processing, when
  * <code>port_thread_postpone_guard_page()</code> function was used
  * to postpone authomatic gurd page restoring.
  *
  * @return 0 on success, system error otherwise.
  *
  * @sa port_thread_postpone_guard_page()
  * @sa port_thread_clear_guard_page()
  */
 int port_thread_restore_guard_page();

 /**
  * Clears guard page in thread's stack on demand.
  * Guard page is cleared automatically for stack overflow processing; this
  * function allows clearing it when needed for other purposes.
  * Guard page can be restored with
  * <code>port_thread_postpone_guard_page()</code> function.
  *
  * @return 0 on success, system error otherwise.
  *
  * @sa port_thread_restore_guard_page()
  */
 int port_thread_clear_guard_page();

 /**
  * Postpones automatic guard page restoring after stack overflow processing.
  *
  * This function can be used inside of STACK_OVERFLOW signal callback to
  * disable automatic guard poge restoring. This is useful when the program
  * expects to consume some more stack before unwinding to SO handler.
  *
  * @sa port_thread_restore_guard_page()
  */
 void port_thread_postpone_guard_page();


 /**
  * Returns stack bottom address for the current thread.
  *
  * @return              NULL on error
  */
 void* port_thread_get_stack_address();


 /**
  * Returns total thread's stack size for the current thread.
  *
  * @return              0 on error
  */
 size_t port_thread_get_stack_size();


 /**
  * Returns effective stack size for the current thread.
  * Effective stack size is an area from stack bottom to guard page.
  *
  * Return value depends thread's state. When the thread is not in signal,
  * return value is a total stack size excluding system page, i.e.
  * (port_thread_get_stack_size() - <guard page size>). When processing a signal,
  * return value is the same when guard page is cleared, and is a size of area
  * from stack bottom to Port's guard page otherwise.
  *
  * @return              0 on error
  */
 size_t port_thread_get_effective_stack_size();


 /**
  * Adjusts priority of the running thread.
  *
  * @param thread        handle of thread
  * @param priority      new priority value
  *
  * @return              0 on success, system error otherwise
  */
 int port_thread_set_priority(osthread_t thread, int priority);

 /**
  * Returns os handle of the current thread.
  *
  * @return current thread handle on success, NULL on error
  *
  * @note The handle returned need to be freed by port_thread_free_handle()
  * @sa port_thread_free_handle()
  */
 osthread_t port_thread_current();

 /**
  * Frees thread handle returned by port_thread_current()
  *
  * @param os_thread     thread handle
  *
  * @sa port_thread_current()
  */
 int port_thread_free_handle(osthread_t os_thread);

 /**
  * Joins the os thread.
  *
  * @param os_thread     thread handle
  *
  * @return              0 on success, systerm error otherwise
  */
 int port_thread_join(osthread_t os_thread);

 /**
  * Terminates the os thread.
  *
  * @param os_thread     thread to terminate
  */
 int port_thread_cancel(osthread_t os_thread);

 /**
  * Causes the current thread to stop execution.
  *
  * @param status        return status of a thread
  */
 void port_thread_exit(int status);

 /**
  * Queries amount of user and kernel times consumed by the thread,
  * in nanoseconds.
  *
  * @param os_thread     thread handle
  * @param[out] pkernel  a pointer to a variable to store kernel time to
  * @param[out] puser    a pointer to a variable to store user time to
  *
  * @return      0 on success, system error otherwise
  */
 int port_get_thread_times(osthread_t os_thread, int64* pkernel, int64* puser);

 /**
  * Causes the other thread to have a memory barrier by suspending
  * and resuming it.
  *
  * @param thread     thread handle
  */
 void port_thread_yield_other(osthread_t thread);

 /**
  * Suspend given thread
  *
  * @param thread The thread to suspend
  */
 int port_thread_suspend(osthread_t thread);

 /**
  * Resume given thread
  *
  * @param thread The thread to resume
  */
 int port_thread_resume(osthread_t thread);

 /**
  * Returnd suspend count for the given thread
  *
  * @param thread The thread to check
  *
  * @return suspend count of the thread, -1 if error
  */
 int port_thread_get_suspend_count(osthread_t thread);

 /**
  * Get context for given thread
  *
  * @param thread The thread to process
  * @param context Pointer to platform-dependent context structure
  *
  * @return 0 if successful, -1 otherwise
  *
  * @note The thread must be suspended
  */
 int port_thread_get_context(osthread_t thread, thread_context_t* pcontext);

 /**
  * Set context for given thread
  *
  * @param thread The thread to process
  * @param context Pointer to platform-dependent context structure
  *
  * @return 0 if successful, -1 otherwise
  *
  * @note The thread must be suspended
  */
 int port_thread_set_context(osthread_t thread, thread_context_t* pcontext);

 /**
  * Translates platform-dependent thread context to Registers structure
  *
  * @param regs Pointer to Registers structure
  * @param context Pointer to platform-dependent context structure
  */
 void port_thread_context_to_regs(Registers* regs, thread_context_t* context);

 /**
  * Translates Registers structure to platform-dependent thread context
  *
  * @param context Pointer to platform-dependent context structure
  * @param regs Pointer to Registers structure
  */
 void port_thread_regs_to_context(thread_context_t* context, Registers* regs);


 //@}

 #ifdef __cplusplus
 }
 #endif

 #endif  /* _PORT_THREAD_H_ */
	/*
	* 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 _PORT_THREAD_H_
	#define _PORT_THREAD_H_

	/**
	* @file port_thread.h
	* @brief PORT thread support
	*/

	/* osthread_t and thread_context_t types, and proper windows.h inclusion */
	#include "open/hythread_ext.h"

	#include "port_general.h"

	/* Thread context definition for UNIX-like systems */
	#if defined(LINUX) \|\| defined(FREEBSD)
	#if defined(LINUX)

	#include <sys/types.h>
	#include <linux/unistd.h>
	#include <errno.h>

	#ifdef _syscall0
	static _syscall0(pid_t, gettid)/* static definition */
	#else /* _syscall0 */
	#include <sys/syscall.h>
	#include <unistd.h>
	#define gettid() ((pid_t)syscall(__NR_gettid))
	#endif /* _syscall0 */

	#else /* !LINUX */
	#include <sys/types.h>
	#include <unistd.h>
	#define gettid() getpid()
	#endif

	#endif /* LINUX \|\| FREEBSD */


	/* To skip platform_types.h inclusion */
	typedef struct Registers Registers;

	#ifdef __cplusplus
	extern "C" {
	#endif /* __cplusplus */


	/** @name OS thread operations
	*/
	//@{

	PORT_INLINE int port_gettid()
	{
	#ifdef PLATFORM_POSIX
	return gettid();
	#else
	return (int)GetCurrentThreadId();
	#endif
	}

	/**
	* The type of pointer to thread start function
	* Function receives single argument - user-defined pointer
	*/
	typedef int (PORT_CDECL port_threadfunc_t)(void);

	/**
	* Creates new thread.
	*
	* @param[out] handle on success, thread handle is stored in memory pointed by handle
	* @param stacksize size of stack to be allocated for a new thread
	* @param priority priority of a new thread
	* @param func function to be started on a new thread
	* @param data value to be passed to a function started on a new thread
	*
	* @return 0 on success, system error otherwise.
	*/
	int port_thread_create(osthread_t* phandle, size_t stacksize, int priority,
	port_threadfunc_t func, void *data);

	/**
	* Attaches current thread to the porting library.
	*
	* This includes setting guard page in thread's stack memory and setting
	* alternative stack for stack overflow processing.
	* This function should be called for any thread which can produce expected
	* hardware signals/exceptions, to guarantee proper signals processing.
	*
	* @return 0 on success, system error otherwise.
	*
	* @sa port_thread_detach()
	*/
	int port_thread_attach();

	/**
	* Detaches current thread from the porting library.
	* This includes restoring thread's stack settings.
	*
	* @return 0 on success, system error otherwise.
	*
	* @sa port_thread_attach()
	*/
	int port_thread_detach();

	/**
	* Restores guard page after stack overflow processing, when
	* <code>port_thread_postpone_guard_page()</code> function was used
	* to postpone authomatic gurd page restoring.
	*
	* @return 0 on success, system error otherwise.
	*
	* @sa port_thread_postpone_guard_page()
	* @sa port_thread_clear_guard_page()
	*/
	int port_thread_restore_guard_page();

	/**
	* Clears guard page in thread's stack on demand.
	* Guard page is cleared automatically for stack overflow processing; this
	* function allows clearing it when needed for other purposes.
	* Guard page can be restored with
	* <code>port_thread_postpone_guard_page()</code> function.
	*
	* @return 0 on success, system error otherwise.
	*
	* @sa port_thread_restore_guard_page()
	*/
	int port_thread_clear_guard_page();

	/**
	* Postpones automatic guard page restoring after stack overflow processing.
	*
	* This function can be used inside of STACK_OVERFLOW signal callback to
	* disable automatic guard poge restoring. This is useful when the program
	* expects to consume some more stack before unwinding to SO handler.
	*
	* @sa port_thread_restore_guard_page()
	*/
	void port_thread_postpone_guard_page();


	/**
	* Returns stack bottom address for the current thread.
	*
	* @return NULL on error
	*/
	void* port_thread_get_stack_address();


	/**
	* Returns total thread's stack size for the current thread.
	*
	* @return 0 on error
	*/
	size_t port_thread_get_stack_size();


	/**
	* Returns effective stack size for the current thread.
	* Effective stack size is an area from stack bottom to guard page.
	*
	* Return value depends thread's state. When the thread is not in signal,
	* return value is a total stack size excluding system page, i.e.
	* (port_thread_get_stack_size() - <guard page size>). When processing a signal,
	* return value is the same when guard page is cleared, and is a size of area
	* from stack bottom to Port's guard page otherwise.
	*
	* @return 0 on error
	*/
	size_t port_thread_get_effective_stack_size();


	/**
	* Adjusts priority of the running thread.
	*
	* @param thread handle of thread
	* @param priority new priority value
	*
	* @return 0 on success, system error otherwise
	*/
	int port_thread_set_priority(osthread_t thread, int priority);

	/**
	* Returns os handle of the current thread.
	*
	* @return current thread handle on success, NULL on error
	*
	* @note The handle returned need to be freed by port_thread_free_handle()
	* @sa port_thread_free_handle()
	*/
	osthread_t port_thread_current();

	/**
	* Frees thread handle returned by port_thread_current()
	*
	* @param os_thread thread handle
	*
	* @sa port_thread_current()
	*/
	int port_thread_free_handle(osthread_t os_thread);

	/**
	* Joins the os thread.
	*
	* @param os_thread thread handle
	*
	* @return 0 on success, systerm error otherwise
	*/
	int port_thread_join(osthread_t os_thread);

	/**
	* Terminates the os thread.
	*
	* @param os_thread thread to terminate
	*/
	int port_thread_cancel(osthread_t os_thread);

	/**
	* Causes the current thread to stop execution.
	*
	* @param status return status of a thread
	*/
	void port_thread_exit(int status);

	/**
	* Queries amount of user and kernel times consumed by the thread,
	* in nanoseconds.
	*
	* @param os_thread thread handle
	* @param[out] pkernel a pointer to a variable to store kernel time to
	* @param[out] puser a pointer to a variable to store user time to
	*
	* @return 0 on success, system error otherwise
	*/
	int port_get_thread_times(osthread_t os_thread, int64* pkernel, int64* puser);

	/**
	* Causes the other thread to have a memory barrier by suspending
	* and resuming it.
	*
	* @param thread thread handle
	*/
	void port_thread_yield_other(osthread_t thread);

	/**
	* Suspend given thread
	*
	* @param thread The thread to suspend
	*/
	int port_thread_suspend(osthread_t thread);

	/**
	* Resume given thread
	*
	* @param thread The thread to resume
	*/
	int port_thread_resume(osthread_t thread);

	/**
	* Returnd suspend count for the given thread
	*
	* @param thread The thread to check
	*
	* @return suspend count of the thread, -1 if error
	*/
	int port_thread_get_suspend_count(osthread_t thread);

	/**
	* Get context for given thread
	*
	* @param thread The thread to process
	* @param context Pointer to platform-dependent context structure
	*
	* @return 0 if successful, -1 otherwise
	*
	* @note The thread must be suspended
	*/
	int port_thread_get_context(osthread_t thread, thread_context_t* pcontext);

	/**
	* Set context for given thread
	*
	* @param thread The thread to process
	* @param context Pointer to platform-dependent context structure
	*
	* @return 0 if successful, -1 otherwise
	*
	* @note The thread must be suspended
	*/
	int port_thread_set_context(osthread_t thread, thread_context_t* pcontext);

	/**
	* Translates platform-dependent thread context to Registers structure
	*
	* @param regs Pointer to Registers structure
	* @param context Pointer to platform-dependent context structure
	*/
	void port_thread_context_to_regs(Registers* regs, thread_context_t* context);

	/**
	* Translates Registers structure to platform-dependent thread context
	*
	* @param context Pointer to platform-dependent context structure
	* @param regs Pointer to Registers structure
	*/
	void port_thread_regs_to_context(thread_context_t* context, Registers* regs);



	//@}

	#ifdef __cplusplus
	}
	#endif

	#endif /* _PORT_THREAD_H_ */