287 lines
7.7 KiB
C++
287 lines
7.7 KiB
C++
/*
|
|
* synergy -- mouse and keyboard sharing utility
|
|
* Copyright (C) 2002 Chris Schoeneman
|
|
*
|
|
* This package is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License
|
|
* found in the file COPYING that should have accompanied this file.
|
|
*
|
|
* This package 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.
|
|
*/
|
|
|
|
#ifndef IARCHMULTITHREAD_H
|
|
#define IARCHMULTITHREAD_H
|
|
|
|
#include "IInterface.h"
|
|
|
|
/*!
|
|
\class CArchCondImpl
|
|
\brief Internal condition variable data.
|
|
An architecture dependent type holding the necessary data for a
|
|
condition variable.
|
|
*/
|
|
class CArchCondImpl;
|
|
|
|
/*!
|
|
\var CArchCond
|
|
\brief Opaque condition variable type.
|
|
An opaque type representing a condition variable.
|
|
*/
|
|
typedef CArchCondImpl* CArchCond;
|
|
|
|
/*!
|
|
\class CArchMutexImpl
|
|
\brief Internal mutex data.
|
|
An architecture dependent type holding the necessary data for a mutex.
|
|
*/
|
|
class CArchMutexImpl;
|
|
|
|
/*!
|
|
\var CArchMutex
|
|
\brief Opaque mutex type.
|
|
An opaque type representing a mutex.
|
|
*/
|
|
typedef CArchMutexImpl* CArchMutex;
|
|
|
|
/*!
|
|
\class CArchThreadImpl
|
|
\brief Internal thread data.
|
|
An architecture dependent type holding the necessary data for a thread.
|
|
*/
|
|
class CArchThreadImpl;
|
|
|
|
/*!
|
|
\var CArchThread
|
|
\brief Opaque thread type.
|
|
An opaque type representing a thread.
|
|
*/
|
|
typedef CArchThreadImpl* CArchThread;
|
|
|
|
//! Interface for architecture dependent multithreading
|
|
/*!
|
|
This interface defines the multithreading operations required by
|
|
synergy. Each architecture must implement this interface.
|
|
*/
|
|
class IArchMultithread : public IInterface {
|
|
public:
|
|
//! Result of waitForEvent()
|
|
enum EWaitResult {
|
|
kEvent, //!< An event is pending
|
|
kExit, //!< Thread exited
|
|
kTimeout //!< Wait timed out
|
|
};
|
|
|
|
//! Type of thread entry point
|
|
typedef void* (*ThreadFunc)(void*);
|
|
//! Type of thread identifier
|
|
typedef unsigned int ThreadID;
|
|
|
|
//! @name manipulators
|
|
//@{
|
|
|
|
//
|
|
// condition variable methods
|
|
//
|
|
|
|
//! Create a condition variable
|
|
/*!
|
|
The condition variable is an opaque data type.
|
|
*/
|
|
virtual CArchCond newCondVar() = 0;
|
|
|
|
//! Destroy a condition variable
|
|
virtual void closeCondVar(CArchCond) = 0;
|
|
|
|
//! Signal a condition variable
|
|
/*!
|
|
Signalling a condition variable releases one waiting thread.
|
|
*/
|
|
virtual void signalCondVar(CArchCond) = 0;
|
|
|
|
//! Broadcast a condition variable
|
|
/*!
|
|
Broadcasting a condition variable releases all waiting threads.
|
|
*/
|
|
virtual void broadcastCondVar(CArchCond) = 0;
|
|
|
|
//! Wait on a condition variable
|
|
/*!
|
|
Wait on a conditation variable for up to \c timeout seconds.
|
|
If \c timeout is < 0 then there is no timeout. The mutex must
|
|
be locked when this method is called. The mutex is unlocked
|
|
during the wait and locked again before returning. Returns
|
|
true if the condition variable was signalled and false on
|
|
timeout.
|
|
|
|
(Cancellation point)
|
|
*/
|
|
virtual bool waitCondVar(CArchCond, CArchMutex, double timeout) = 0;
|
|
|
|
//
|
|
// mutex methods
|
|
//
|
|
|
|
//! Create a recursive mutex
|
|
/*!
|
|
Creates a recursive mutex. A thread may lock a recursive mutex
|
|
when it already holds a lock on that mutex. The mutex is an
|
|
opaque data type.
|
|
*/
|
|
virtual CArchMutex newMutex() = 0;
|
|
|
|
//! Destroy a mutex
|
|
virtual void closeMutex(CArchMutex) = 0;
|
|
|
|
//! Lock a mutex
|
|
/*!
|
|
(Cancellation point)
|
|
*/
|
|
virtual void lockMutex(CArchMutex) = 0;
|
|
|
|
//! Unlock a mutex
|
|
virtual void unlockMutex(CArchMutex) = 0;
|
|
|
|
//
|
|
// thread methods
|
|
//
|
|
|
|
//! Start a new thread
|
|
/*!
|
|
Creates and starts a new thread, using \c func as the entry point
|
|
and passing it \c userData. The thread is an opaque data type.
|
|
*/
|
|
virtual CArchThread newThread(ThreadFunc func, void* userData) = 0;
|
|
|
|
//! Get a reference to the calling thread
|
|
/*!
|
|
Returns a thread representing the current (i.e. calling) thread.
|
|
*/
|
|
virtual CArchThread newCurrentThread() = 0;
|
|
|
|
//! Copy a thread object
|
|
/*!
|
|
Returns a reference to to thread referred to by \c thread.
|
|
*/
|
|
virtual CArchThread copyThread(CArchThread thread) = 0;
|
|
|
|
//! Release a thread reference
|
|
/*!
|
|
Deletes the given thread object. This does not destroy the thread
|
|
the object referred to, even if there are no remaining references.
|
|
Use cancelThread() and waitThread() to stop a thread and wait for
|
|
it to exit.
|
|
*/
|
|
virtual void closeThread(CArchThread) = 0;
|
|
|
|
//! Force a thread to exit
|
|
/*!
|
|
Causes \c thread to exit when it next calls a cancellation point.
|
|
A thread avoids cancellation as long as it nevers calls a
|
|
cancellation point. Once it begins the cancellation process it
|
|
must always let cancellation go to completion but may take as
|
|
long as necessary to clean up.
|
|
*/
|
|
virtual void cancelThread(CArchThread thread) = 0;
|
|
|
|
//! Change thread priority
|
|
/*!
|
|
Changes the priority of \c thread by \c n. If \c n is positive
|
|
the thread has a lower priority and if negative a higher priority.
|
|
Some architectures may not support either or both directions.
|
|
*/
|
|
virtual void setPriorityOfThread(CArchThread, int n) = 0;
|
|
|
|
//! Cancellation point
|
|
/*!
|
|
This method does nothing but is a cancellation point. Clients
|
|
can make their own functions cancellation points by calling this
|
|
method at appropriate times.
|
|
*/
|
|
virtual void testCancelThread() = 0;
|
|
|
|
//! Wait for a thread to exit
|
|
/*!
|
|
Waits for up to \c timeout seconds for \c thread to exit (normally
|
|
or by cancellation). Waits forever if \c timeout < 0. Returns
|
|
true if the thread exited, false otherwise. Waiting on the current
|
|
thread returns immediately with false.
|
|
|
|
(Cancellation point)
|
|
*/
|
|
virtual bool wait(CArchThread thread, double timeout) = 0;
|
|
|
|
//! Wait for a user event
|
|
/*!
|
|
Waits for up to \c timeout seconds for a pending user event or
|
|
\c thread to exit (normally or by cancellation). Waits forever
|
|
if \c timeout < 0. Returns kEvent if an event occurred, kExit
|
|
if \c thread exited, or kTimeout if the timeout expired. If
|
|
\c thread is NULL then it doesn't wait for any thread to exit
|
|
and it will not return kExit.
|
|
|
|
This method is not required by all platforms.
|
|
|
|
(Cancellation point)
|
|
*/
|
|
virtual EWaitResult waitForEvent(CArchThread thread, double timeout) = 0;
|
|
|
|
//! Unblock thread in system call
|
|
/*!
|
|
Cause a thread that's in a blocking system call to return. This
|
|
call may return before the thread is unblocked. If the thread is
|
|
not in a blocking system call, this call has no effect. This does
|
|
not cause a lockMutex() or waitCondVar() to return prematurely.
|
|
*/
|
|
virtual void unblockThread(CArchThread thread) = 0;
|
|
|
|
//! Compare threads
|
|
/*!
|
|
Returns true iff two thread objects refer to the same thread.
|
|
Note that comparing thread objects directly is meaningless.
|
|
*/
|
|
virtual bool isSameThread(CArchThread, CArchThread) = 0;
|
|
|
|
//! Test if thread exited
|
|
/*!
|
|
Returns true iff \c thread has exited.
|
|
*/
|
|
virtual bool isExitedThread(CArchThread thread) = 0;
|
|
|
|
//! Returns the exit code of a thread
|
|
/*!
|
|
Waits indefinitely for \c thread to exit (if it hasn't yet) then
|
|
returns the thread's exit code.
|
|
|
|
(Cancellation point)
|
|
*/
|
|
virtual void* getResultOfThread(CArchThread thread) = 0;
|
|
|
|
//! Returns an ID for a thread
|
|
/*!
|
|
Returns some ID number for \c thread. This is for logging purposes.
|
|
All thread objects referring to the same thread return the same ID.
|
|
However, clients should us isSameThread() to compare thread objects
|
|
instead of comparing IDs.
|
|
*/
|
|
virtual ThreadID getIDOfThread(CArchThread thread) = 0;
|
|
|
|
//! Set the interrupt handler
|
|
/*!
|
|
Sets the function to call on receipt of an external interrupt.
|
|
By default and when \p func is NULL, the main thread is cancelled.
|
|
*/
|
|
typedef void (*InterruptFunc)(void*);
|
|
virtual void setInterruptHandler(InterruptFunc func,
|
|
void* userData) = 0;
|
|
|
|
//! Invoke the interrupt handler
|
|
virtual void interrupt() = 0;
|
|
|
|
//@}
|
|
};
|
|
|
|
#endif
|