src/common/Thread.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *   Copyright (C) 2005 - 2020 Christian Schoenebeck                       *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program 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, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef __LS_THREAD_H__
#define __LS_THREAD_H__

//FIXME: this is a temorary solution because of problems with condition variables we use a polling lock in SignalStartThread()
#if defined(WIN32)
#define WIN32_SIGNALSTARTTHREAD_WORKAROUND 1
#endif

#include <iostream>
#include <stdio.h>
#include <stdlib.h>

#if defined(WIN32)
#include <windows.h>
#else
#include <sched.h>
#include <sys/mman.h>
#include <memory.h>
#include <pthread.h>
#endif
#include <errno.h>

#include "Condition.h"

namespace LinuxSampler {

/**
 * Abstract base class for classes that need to run in an own thread. The
 * deriving class needs to implement the abstract method Main() for the actual
 * task of the thread to be implemented.
 *
 * @b IMPORTANT: You @b MUST call StopThread() before destructing a running
 * Thread object! Destructing the Thread object without stopping it first can
 * lead to undefined behavior! The destructor will detect if the thread is still
 * running and will stop it automatically in this case, however once the
 * destructor is entered, this Thread object's vpointer is already been
 * modified, so if the thread is still running at this point this would cause a
 * data race condition since the active thread is calling virtual methods and
 * thus this can lead to undefined behavior.
 */
class Thread {
    public:
        Thread(bool LockMemory, bool RealTime, int PriorityMax, int PriorityDelta);
        virtual ~Thread();
        virtual int  StartThread();
        virtual int  StopThread();
        virtual int  SignalStopThread();
        virtual bool IsRunning();

        /**
         * Allocates an aligned block of memory. Allocated memory blocks
         * need to be freed using freeAlignedMem().
         *
         * @param boundary - the alignement boundary, usually a power of 2
         *                   e.g. 4 but it can be an arbitrary number
         *                   between 1 and 128
         * @param size     - size in bytes to be allocated
         * @returns  pointer to the allocated memory block
         */
        static void* allocAlignedMem(size_t boundary, size_t size) {
            unsigned char *ptr = (unsigned char *)malloc(size+boundary);
            size_t offset = boundary - ((size_t)ptr % boundary);
            ptr[offset-1] = (unsigned char)offset;
            return (ptr + offset);
        }

        /**
         * Frees an aligned block of memory allocated with allocAlignedMem()
         *
         * @param ptr - pointer to the memory block
         */
        static void freeAlignedMem(void *ptr) {
            unsigned char *p = (unsigned char *)ptr;
            p -= p[-1];
            free(p);
        }

        /**
         * Locks a region of memory in physical RAM.
         *
         * @param addr - address of the memory block
         * @param size - size of the memory block
         * @return true if the locking succeded, otherwise false
         */
        static bool lockMemory(void *addr, size_t size) {
            #if defined(WIN32)
            return VirtualLock(addr, size);
            #else
            return !mlock(addr, size);
            #endif
        }

        /**
         * Unlocks a region of memory in physical RAM.
         *
         * @param addr - address of the memory block
         * @param size - size of the memory block
         * @return true if the unlocking succeded, otherwise false
         */
        static bool unlockMemory(void *addr, size_t size) {
            #if defined(WIN32)
            return VirtualUnlock(addr, size);
            #else
            return !munlock(addr, size);
            #endif
        }

        static void pushCancelable(bool cancel);
        static void popCancelable();

        std::string name();
        static std::string nameOfCaller();
        static void setNameOfCaller(std::string name);

    protected:
        /**
         * This method needs to be implemented by the descending class and is
         * the entry point for the new thread.
         *
         * @b NOTE: If your thread runs for a longer time, i.e. if it is running
         * a loop, then you should explicitly call TestCancel() once in a while
         * in your Main() implementation, especially if your implementation does
         * not use any system calls.
         */
        virtual int Main() = 0;

        /**
         * Synchronization point for potentially terminating the thread. Like
         * already described in Main() you should call TestCancel() in your
         * Main() implementation once in a while to provide the system a chance
         * to perform a clean termination of your thread. Depending on the
         * underlying OS, and also depending on whether your are using any
         * system call in your Main() implementation, it might otherwise be
         * possible that the thread cannot be terminated at all! And even if the
         * underlying OS supports terminating busy threads which do not call
         * TestCancel(), this might still cause undefined behavior on such OSes!
         */
        void TestCancel();

        virtual int  SignalStartThread();
        virtual int  SetSchedulingPriority();
        virtual int  LockMemory();
        virtual void EnableDestructor();
        virtual int  onThreadEnd();

    private:
        enum state_t {
            NOT_RUNNING,
            RUNNING,
            PENDING_JOIN,
            DETACHED
        };

    #if defined(WIN32)
        HANDLE hThread;
        DWORD lpThreadId;
        #if defined(WIN32_SIGNALSTARTTHREAD_WORKAROUND)
        bool win32isRunning;
        #endif
    #else
        pthread_attr_t  __thread_attr;
        pthread_t       __thread_id;
        pthread_key_t   __thread_destructor_key;
    #endif
        Condition       RunningCondition;
        int             PriorityMax;
        int             PriorityDelta;
        bool            isRealTime;
        bool            bLockedMemory;
        state_t         state;

    #if defined(WIN32)
        static DWORD WINAPI win32threadLauncher(LPVOID lpParameter);
    #else
        static void* pthreadLauncher(void* thread);
        static void  pthreadDestructor(void* thread);
    #endif
};

} // namespace LinuxSampler

#endif // __LS_THREAD_H__
1	schoenebeck	53	/***************************************************************************
2			* *
3			* LinuxSampler - modular, streaming capable sampler *
4			* *
5	schoenebeck	56	* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	schoenebeck	3764	* Copyright (C) 2005 - 2020 Christian Schoenebeck *
7	schoenebeck	53	* *
8			* This program is free software; you can redistribute it and/or modify *
9			* it under the terms of the GNU General Public License as published by *
10			* the Free Software Foundation; either version 2 of the License, or *
11			* (at your option) any later version. *
12			* *
13			* This program is distributed in the hope that it will be useful, *
14			* but WITHOUT ANY WARRANTY; without even the implied warranty of *
15			* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
16			* GNU General Public License for more details. *
17			* *
18			* You should have received a copy of the GNU General Public License *
19			* along with this program; if not, write to the Free Software *
20			* Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
21			* MA 02111-1307 USA *
22			***************************************************************************/
23
24	schoenebeck	1424	#ifndef __LS_THREAD_H__
25			#define __LS_THREAD_H__
26	schoenebeck	53
27	schoenebeck	1482	//FIXME: this is a temorary solution because of problems with condition variables we use a polling lock in SignalStartThread()
28			#if defined(WIN32)
29	senoner	1481	#define WIN32_SIGNALSTARTTHREAD_WORKAROUND 1
30	schoenebeck	1482	#endif
31	senoner	1481
32	schoenebeck	53	#include <iostream>
33			#include <stdio.h>
34			#include <stdlib.h>
35	senoner	1481
36			#if defined(WIN32)
37			#include <windows.h>
38			#else
39	schoenebeck	53	#include <sched.h>
40			#include <sys/mman.h>
41			#include <memory.h>
42			#include <pthread.h>
43	senoner	1481	#endif
44	schoenebeck	53	#include <errno.h>
45
46	schoenebeck	1221	#include "Condition.h"
47
48	schoenebeck	1212	namespace LinuxSampler {
49
50	schoenebeck	3290	/**
51			* Abstract base class for classes that need to run in an own thread. The
52			* deriving class needs to implement the abstract method Main() for the actual
53			* task of the thread to be implemented.
54			*
55			* @b IMPORTANT: You @b MUST call StopThread() before destructing a running
56			* Thread object! Destructing the Thread object without stopping it first can
57			* lead to undefined behavior! The destructor will detect if the thread is still
58			* running and will stop it automatically in this case, however once the
59			* destructor is entered, this Thread object's vpointer is already been
60			* modified, so if the thread is still running at this point this would cause a
61			* data race condition since the active thread is calling virtual methods and
62			* thus this can lead to undefined behavior.
63			*/
64	schoenebeck	53	class Thread {
65			public:
66	schoenebeck	392	Thread(bool LockMemory, bool RealTime, int PriorityMax, int PriorityDelta);
67	schoenebeck	53	virtual ~Thread();
68			virtual int StartThread();
69			virtual int StopThread();
70			virtual int SignalStopThread();
71	schoenebeck	1212	virtual bool IsRunning();
72	senoner	1481
73	schoenebeck	1482	/**
74			* Allocates an aligned block of memory. Allocated memory blocks
75			* need to be freed using freeAlignedMem().
76			*
77			* @param boundary - the alignement boundary, usually a power of 2
78			* e.g. 4 but it can be an arbitrary number
79			* between 1 and 128
80			* @param size - size in bytes to be allocated
81			* @returns pointer to the allocated memory block
82			*/
83	senoner	1481	static void* allocAlignedMem(size_t boundary, size_t size) {
84			unsigned char ptr = (unsigned char )malloc(size+boundary);
85			size_t offset = boundary - ((size_t)ptr % boundary);
86			ptr[offset-1] = (unsigned char)offset;
87			return (ptr + offset);
88			}
89
90	schoenebeck	1482	/**
91			* Frees an aligned block of memory allocated with allocAlignedMem()
92			*
93			* @param ptr - pointer to the memory block
94			*/
95	senoner	1481	static void freeAlignedMem(void *ptr) {
96			unsigned char p = (unsigned char )ptr;
97			p -= p[-1];
98			free(p);
99			}
100	schoenebeck	1482
101	senoner	1481	/**
102	schoenebeck	1482	* Locks a region of memory in physical RAM.
103			*
104			* @param addr - address of the memory block
105			* @param size - size of the memory block
106			* @return true if the locking succeded, otherwise false
107			*/
108	senoner	1481	static bool lockMemory(void *addr, size_t size) {
109			#if defined(WIN32)
110			return VirtualLock(addr, size);
111			#else
112			return !mlock(addr, size);
113			#endif
114			}
115	schoenebeck	1482
116	senoner	1481	/**
117	schoenebeck	1482	* Unlocks a region of memory in physical RAM.
118			*
119			* @param addr - address of the memory block
120			* @param size - size of the memory block
121			* @return true if the unlocking succeded, otherwise false
122			*/
123	senoner	1481	static bool unlockMemory(void *addr, size_t size) {
124			#if defined(WIN32)
125			return VirtualUnlock(addr, size);
126			#else
127			return !munlock(addr, size);
128			#endif
129			}
130	schoenebeck	1482
131	schoenebeck	3764	static void pushCancelable(bool cancel);
132			static void popCancelable();
133
134			std::string name();
135			static std::string nameOfCaller();
136			static void setNameOfCaller(std::string name);
137
138	schoenebeck	3290	protected:
139			/**
140			* This method needs to be implemented by the descending class and is
141			* the entry point for the new thread.
142			*
143			* @b NOTE: If your thread runs for a longer time, i.e. if it is running
144			* a loop, then you should explicitly call TestCancel() once in a while
145			* in your Main() implementation, especially if your implementation does
146			* not use any system calls.
147			*/
148			virtual int Main() = 0;
149
150			/**
151			* Synchronization point for potentially terminating the thread. Like
152			* already described in Main() you should call TestCancel() in your
153			* Main() implementation once in a while to provide the system a chance
154			* to perform a clean termination of your thread. Depending on the
155			* underlying OS, and also depending on whether your are using any
156			* system call in your Main() implementation, it might otherwise be
157			* possible that the thread cannot be terminated at all! And even if the
158			* underlying OS supports terminating busy threads which do not call
159			* TestCancel(), this might still cause undefined behavior on such OSes!
160			*/
161			void TestCancel();
162
163			virtual int SignalStartThread();
164			virtual int SetSchedulingPriority();
165			virtual int LockMemory();
166			virtual void EnableDestructor();
167			virtual int onThreadEnd();
168
169	schoenebeck	53	private:
170	schoenebeck	3290	enum state_t {
171			NOT_RUNNING,
172			RUNNING,
173			PENDING_JOIN,
174			DETACHED
175			};
176
177	senoner	1481	#if defined(WIN32)
178			HANDLE hThread;
179			DWORD lpThreadId;
180			#if defined(WIN32_SIGNALSTARTTHREAD_WORKAROUND)
181			bool win32isRunning;
182			#endif
183			#else
184	schoenebeck	1221	pthread_attr_t __thread_attr;
185	schoenebeck	53	pthread_t __thread_id;
186			pthread_key_t __thread_destructor_key;
187	senoner	1481	#endif
188	schoenebeck	1221	Condition RunningCondition;
189	schoenebeck	53	int PriorityMax;
190			int PriorityDelta;
191			bool isRealTime;
192	schoenebeck	1653	bool bLockedMemory;
193	schoenebeck	3290	state_t state;
194
195			#if defined(WIN32)
196			static DWORD WINAPI win32threadLauncher(LPVOID lpParameter);
197			#else
198			static void* pthreadLauncher(void* thread);
199			static void pthreadDestructor(void* thread);
200			#endif
201	schoenebeck	53	};
202
203	schoenebeck	1212	} // namespace LinuxSampler
204
205	schoenebeck	1424	#endif // __LS_THREAD_H__