the begginning

utils/rwlock/rwlock.h

@@ -0,0 +1,253 @@
+/* Copyright (C) 2014 InfiniDB, Inc.
+
+   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; version 2 of
+   the License.
+
+   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., 51 Franklin Street, Fifth Floor, Boston,
+   MA 02110-1301, USA. */
+
+/******************************************************************************
+ * $Id$
+ *
+ *****************************************************************************/
+
+/** @file 
+ * class RWLock interface
+ */
+
+#ifndef RWLOCK_H_
+#define RWLOCK_H_
+
+#include <unistd.h>
+#include <stdexcept>
+
+#include <boost/interprocess/shared_memory_object.hpp>
+#include <boost/interprocess/mapped_region.hpp>
+#include <boost/interprocess/sync/interprocess_semaphore.hpp>
+#include <boost/date_time/posix_time/posix_time.hpp>
+
+#if defined(_MSC_VER) && defined(xxxRWLOCK_DLLEXPORT)
+#define EXPORT __declspec(dllexport)
+#else
+#define EXPORT
+#endif
+
+namespace rwlock
+{
+
+/// the layout of the shmseg
+struct State {
+#ifdef _MSC_VER
+	volatile LONG writerswaiting;
+	volatile LONG writing;
+	volatile LONG readerswaiting;
+	volatile LONG reading;
+#else
+	volatile int writerswaiting;
+	volatile int writing;
+	volatile int readerswaiting;
+	volatile int reading;
+#endif
+	boost::interprocess::interprocess_semaphore sems[3];
+};
+
+/* the lock state without the semaphores, passed out by timed_write_lock() for
+class RWLockMonitor
+*/
+struct LockState {
+#ifdef _MSC_VER
+	LONG writerswaiting;
+	LONG writing;
+	LONG readerswaiting;
+	LONG reading;
+	bool mutexLocked;
+#else
+	int writerswaiting;
+	int writing;
+	int readerswaiting;
+	int reading;
+	bool mutexLocked;
+#endif
+};
+
+class RWLockShmImpl
+{
+public:
+	static RWLockShmImpl* makeRWLockShmImpl(int key, bool* excl=0);
+
+	boost::interprocess::shared_memory_object fStateShm;
+	boost::interprocess::mapped_region fRegion;
+	State *fState;
+
+	std::string keyString() { return fKeyString; }
+private:
+	explicit RWLockShmImpl(int key, bool excl=false);
+	~RWLockShmImpl();
+	RWLockShmImpl(const RWLockShmImpl& rhs);
+	RWLockShmImpl& operator=(const RWLockShmImpl& rhs);
+	std::string fKeyString;
+};
+
+class not_excl : public std::exception
+{
+	public:
+	virtual const char* what() const throw() {
+		return "not_excl";
+	}
+};
+
+class wouldblock : public std::exception
+{
+	public:
+	virtual const char* what() const throw() {
+		return "wouldblock";
+	}
+};
+
+/** @brief Implements RW locks for use across threads & processes
+ * 
+ * Implements RW locks for use across threads & processes.  Every 
+ * instance that shares a lock must be instantiated using the same
+ * key.  There is 'no limit' on the number of RW locks that can 
+ * exist on the system at any one time. 
+ *
+ * Summary of operation:
+ * 		- readers can work concurrently
+ *		- writers get exclusive access
+ * 		- writers have priority
+ *		- all state persists across all invocations sharing a given key
+ *
+ * Note: because state has to persist, it will have to be cleaned
+ * up somewhere else.  Crashes while holding a read or write lock will
+ * eventually deadlock the set of processes that share the same key obviously.
+ */
+class RWLock {
+	public:
+
+		// semaphore numbers
+		static const int MUTEX=0;
+		static const int READERS=1;
+		static const int WRITERS=2;
+
+		/** @brief Keyed constructor.
+		 *
+		 * Instantiate an RWLock with the given key.  All instances that
+		 * share a key share the same lock.
+		 * 
+		 * @param key The key
+		 * @param excl If true and this is the first instance with the 
+		 * supplied key, it will return holding the write lock.  If true and
+		 * this is not the first instance, it will throw not_excl.  The intent
+		 * is similar to the IPC_EXCL flag in the sem/shm implementations.
+		 */
+		EXPORT explicit RWLock(int key, bool* excl = 0);
+
+		EXPORT ~RWLock();
+		
+		/** @brief Grab a read lock
+		 *
+		 * Grab a read lock.  This will block iff writers are waiting or
+		 * a writer is active. The version with priority ignores any 
+		 * waiting threads and grabs the lock. 
+		 * 
+		 * @param block (For testing only) If false, will throw 
+		 * wouldblock instead of blocking
+		 */
+		EXPORT void read_lock(bool block = true);
+
+		EXPORT void read_lock_priority(bool block = true);
+
+		/** @brief Release a read lock.
+		 *
+		 * Release a read lock.
+		 */
+		EXPORT void read_unlock();
+
+		/** @brief Grab a write lock
+		 *
+		 * Grab a write lock.  This will block while another writer or reader is 
+		 * active and will have exclusive access on waking.
+		 *
+		 * @param block (For testing only) If false, will throw 
+		 * wouldblock instead of blocking
+		 */
+		EXPORT void write_lock(bool block = true);
+
+		/** @brief A timed write lock.
+		 *
+		 * Queues up for the write lock for a specified amount of time.  Returns
+		 * true if it got the lock, return false if it timed out first.
+		 * If the timeout happens, it will also return the lock state if passed
+		 * a non-NULL LockState struct.  This is a specialization for supporting
+		 * the RWLockMonitor class.
+		 */
+		EXPORT bool timed_write_lock(const struct timespec &ts,
+				struct LockState *state = 0);
+
+		/** @brief Release a write lock.
+		 *
+		 * Release a write lock.
+		 */
+		EXPORT void write_unlock();
+
+		/* note: these haven't been proven yet */
+		
+		/** @brief Upgrade a read lock to a write lock
+		 *
+		 * Upgrade a read lock to a write lock.  It may have to block
+		 * if there are other readers currently reading.  No guarantees of atomicity.
+		 */
+		EXPORT void upgrade_to_write();
+		
+		/** @brief Downgrade a write lock to a read lock
+		 *
+		 * Downgrade a write lock to a read lock.  The conversion happens 
+		 * atomically.
+		 */
+		EXPORT void downgrade_to_read();
+		
+		/** @brief Reset the lock's state (Use with caution!)
+		 * 
+		 * If the lock gets into a bad state in testing or something,
+		 * this will reset the state.
+		 * @warning This is safe only if there are no other threads using this 
+		 * lock.
+	 	 */
+		EXPORT void reset();
+
+		/* These are for white box testing only */
+		inline void lock() { down(MUTEX, true); }
+		inline void unlock() { up(MUTEX); }
+		inline int getWriting() const { return fPImpl->fState->writing; }
+		inline int getReading() const { return fPImpl->fState->reading; }
+		inline int getWritersWaiting() const { return fPImpl->fState->writerswaiting; }
+		inline int getReadersWaiting() const { return fPImpl->fState->readerswaiting; }
+		LockState getLockState();
+		
+	private:
+		RWLock(const RWLock& rwl);
+		RWLock& operator=(const RWLock& rwl);
+
+		inline int getSemval(int) const { return 0; }
+		void down(int num, bool block = true);
+		bool timed_down(int num, const boost::posix_time::ptime &ts);  // to support timed_write_lock()
+		void up(int num);
+
+		RWLockShmImpl* fPImpl;
+};
+
+} //namespace rwlock
+
+#undef EXPORT
+
+#endif
+// vim:ts=4 sw=4: