v0.3

CHANGELOG.md

@@ -1,19 +1,26 @@
-## v0.3 - XXXX-XX-XX
+## v0.3 - 2020-05-19
 
 ### New features
 
-* Python:
-  * introduced `ObjectHandler`, compatible with CPython's `PyObject *`
-  * added functions `beginCriticalSection()` / `endCriticalSection()`
+* `MutexLock`:
+  * Introduced `Guard` (`std::lock_guard<MutexLock>`)
+* `Python`: 
+  * revisited the whole API to make it simpler to use and more stable:
+    * removed function `arguments()`. Arguments are passed straight as a vector or an initializer list to the `call()` function
+    * functions `tuple()` and `list()` take a vector or an initializer list as an argument. Ellipsis are no longer used.
+    * introduced `ObjectHandler`, silently compatible with CPython `PyObject *` based API 
+  * added functions `beginCriticalSection()` / `endCriticalSection()` to define critical sections in multithreaded applications
   * added unit tests and improved the documentation.
 
 ### Fixes
 
-* Python: fixed a multithreading issue
+* `Python`: fixed a multithreading issue
 
 ### Compatibility breakers
 
-* Python: `ValueRef` and `ArgsRef` have been replaced by `ObjectHandler`. Explicit use of htese types should be replaced in your code. 
+* `Python`: API has been completely revisited (see above), though its philosophy remains unchanged. Changes in your code are expected to be strightforward. 
+* `MutexLock`: renamed `queueLock()` in `lock()`. Your code should be adapted the same way.
+
 
 ## v0.2 - 2020-05-15
 

README.md

@@ -60,8 +60,8 @@ it has no standardized replacement so far.
 ## Installation from binaries
 
 Should you just wish to use Shlublulib as a development tool, the binary distribution can be downloaded from our website:
-* [Linux x86 version](http://shlublulib.shlublu.org/dist/shlublulib-linux-v0.3.zip) ([PGP sig](http://shlublulib.shlublu.org/dist/shlublulib-linux-v0.3.zip.asc) - SHA-256: `4ce0c2cff649297bad791092c6988c9b6023db599efdbf37f949aa284d31dc24`)
-* [Win64 x86 version](http://shlublulib.shlublu.org/dist/shlublulib-win64-v0.3.zip) ([PGP sig](http://shlublulib.shlublu.org/dist/shlublulib-win64-v0.3.zip.asc) - SHA-256: `2ce011a85a25b4b2fe3698318be82fb89fb4a08326eb766f9a1537a82de91420`)
+* [Linux x86 version](http://shlublulib.shlublu.org/dist/shlublulib-linux-v0.3.zip) ([PGP sig](http://shlublulib.shlublu.org/dist/shlublulib-linux-v0.3.zip.asc) - SHA-256: `0ae00fb99fcc1e14d9b7bcf211ef7f1fd1f8e2af8db4e4897179f76e9644c8d2`)
+* [Win64 x86 version](http://shlublulib.shlublu.org/dist/shlublulib-win64-v0.3.zip) ([PGP sig](http://shlublulib.shlublu.org/dist/shlublulib-win64-v0.3.zip.asc) - SHA-256: `6762bcb2d7c16ab68cef2dd03132476d7a7533b6d18b4c57aaa196aba26cda36`)
 
 These archives are signed with [my PGP key](https://keyserver.ubuntu.com/pks/lookup?search=shlublu%40yahoo.fr&fingerprint=on&op=index) and contain:
 * the library file to link to your client programs

include/shlublu/async/MutexLock.h

@@ -18,13 +18,15 @@ namespace shlublu
 
 	<b>Typical examples of use</b>
 	@code
-	MutexLock lock; // shared by MyThreadedTransactionsManager instances
+	MutexLock locker; // shared by MyThreadedTransactionsManager instances
 
 	// ...
 
 	void MyThreadedTransactionsManager::transactionalEnsembleThatDoesNotSupportConcurrency(int someNumericParameter)
 	{
-		lock.queueLock();
+		// ... operations that support concurrency ...
+
+		locker.lock();
 
 		// ... operations that do not support concurrency ...
 
@@ -33,21 +35,58 @@ namespace shlublu
 			singleTransaction(i);
 		}
 
-		lock.unlock();
+		locker.unlock();
+
+		// ... operations that support concurrency ...
 	}
 
 	void MyThreadedTransactionsManager::singleTransaction(int someNumericParameter)
 	{
-		lock.queueLock();
+		// ... operations that support concurrency ...
+
+		locker.lock();
 
 		// ... operations that do not support concurrency ...
 
-		lock.unlock();
+		locker.unlock();
+
+		// ... operations that support concurrency ...
 	}
 	@endcode
  */
 class MutexLock
 {
+public:
+	/**
+		<a href="https://en.cppreference.com/w/cpp/language/raii">RAII</a> convenience wrapper.
+
+		This wrapper guarantees that the mutex will be unlock at the moment its destructor will be called. Used in a function or method, this
+		makes `MutexLock::unlock()` to be called at `return` or `throw` time with no further manual handling.
+
+		Based on the standard `std::lock_guard` implementation.
+		
+		@see <a href="https://www.cplusplus.com/reference/mutex/lock_guard/">std::lock_guard</a>
+
+		<b>Example</b>
+		@code
+		MutexLock locker; // let's assume this is a memeber of MyThreadedTransactionsManager
+
+		// ...
+
+		int MyThreadedTransactionsManager::methodThatDoesNotSupportConcurrency()
+		{
+			MutexLock::Guard(locker);
+
+			int x(someCall());
+
+			// ... operations that do not support concurrency ...
+
+			return x;
+		}
+		@endcode
+	*/
+	using Guard = std::lock_guard<MutexLock>;
+
 public:
 	/**
 		Copy constructor is deleted.
@@ -74,14 +113,14 @@ class MutexLock
 
 public:
 	/**
-		Blocking lock.
+		Locks the mutex once available.
 		Queues until the mutex is available for locking. A lock is available if:
 		<ul>
 		<li>it is in released state
-		<li>it has been previously locked by the thread that is currently attempting to lock
+		<li>it has been previously locked by the same thread as the calling one
 		</ul>
 	*/
-	void queueLock();	
+	void lock();	
 
 	/**
 		Unlocks the mutex.
@@ -94,9 +133,13 @@ class MutexLock
 	void unlock();
 
 private:
+	/// @cond INTERNAL
+
 	std::recursive_mutex mMutex;
 	std::thread::id mOwnerId;
 	int mLockLevel;
+
+	/// @endcond
 };
 
 }