Common: Document sw::Resource

src/Common/Resource.hpp

@@ -27,19 +27,71 @@ namespace sw
 		EXCLUSIVE
 	};
 
+	// Resource is a form of shared mutex that guards an internally allocated
+	// buffer. Resource has an exclusive lock mode (sw::Accessor) and lock
+	// count, defaulting to sw::Accessor::PUBLIC and 0, respectively.
+	// Resource does treat any of the sw::Accessor enumerator lock modes
+	// differently, all semantic meaning comes from the usage of Resource.
+	// You can have multiple locks in mode sw::Accessor::EXCLUSIVE.
 	class Resource
 	{
 	public:
 		Resource(size_t bytes);
 
-		void destruct();   // Asynchronous destructor
+		// destruct() is an asynchronous destructor, that will atomically:
+		//   When the resource is unlocked:
+		//     * Delete itself.
+		//   When the resource is locked:
+		//     * Flag itself for deletion when next fully unlocked.
+		void destruct();
 
+		// lock() will atomically:
+		//   When the resource is unlocked OR the lock mode equals claimer:
+		//     * Increment the lock count.
+		//     * Return a pointer to the buffer.
+		//   When the resource is locked AND the lock mode does not equal claimer:
+		//     * Block until all existing locks are released (lock count equals 0).
+		//     * Switch lock mode to claimer.
+		//     * Increment the lock count.
+		//     * Return a pointer to the buffer.
 		void *lock(Accessor claimer);
+
+		// lock() will atomically:
+		//   When the resource is unlocked OR the lock mode equals claimer:
+		//     * Increment the lock count.
+		//     * Return a pointer to the buffer.
+		//   When the resource is locked AND the lock mode equals relinquisher:
+		//     * Release *all* existing locks (regardless of prior count).
+		//     * Delete itself and return nullptr if Resource::destruct() had been called while locked.
+		//     * Switch lock mode to claimer.
+		//     * Increment the lock count to 1.
+		//     * Return a pointer to the buffer.
+		//   When the resource is locked AND the lock mode does not equal relinquisher:
+		//     * Block until all existing locks are released (lock count equals 0)
+		//     * Switch lock mode to claimer
+		//     * Increment the lock count to 1.
+		//     * Return a pointer to the buffer.
 		void *lock(Accessor relinquisher, Accessor claimer);
+
+		// unlock() will atomically:
+		// * Assert if there are no locks.
+		// * Release a single lock.
+		// * Delete itself if Resource::destruct() had been called while locked.
 		void unlock();
+
+		// unlock() will atomically:
+		//   When the resource is locked AND the lock mode equals relinquisher:
+		//     * Release *all* existing locks (regardless of prior count).
+		//     * Delete itself if Resource::destruct() had been called while locked.
+		//   When the resource is not locked OR the lock mode does not equal relinquisher:
+		//     * Do nothing.
 		void unlock(Accessor relinquisher);
 
+		// data() will return the Resource's buffer pointer regardless of lock
+		// state.
 		const void *data() const;
+
+		// size is the size in bytes of the Resource's buffer.
 		const size_t size;
 
 	private: