From 18656f3ab93699bf81c6d60e28b51cec59987271 Mon Sep 17 00:00:00 2001 From: Tamas Cservenak Date: Tue, 20 Jun 2023 15:06:12 +0200 Subject: [PATCH 1/3] Add a bit more doco --- .../src/site/markdown/index.md.vm | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/maven-resolver-named-locks/src/site/markdown/index.md.vm b/maven-resolver-named-locks/src/site/markdown/index.md.vm index 17486e775..feff7a8ca 100644 --- a/maven-resolver-named-locks/src/site/markdown/index.md.vm +++ b/maven-resolver-named-locks/src/site/markdown/index.md.vm @@ -23,6 +23,22 @@ Named locks are essentially locks that are assigned to some given (opaque) ID. I resources that each can have unique ID assigned (i.e., file with an absolute path, some entities with unique ID), then you can use named locks to make sure they are being protected from concurrent read and write actions. +The building block for named locks is `org.eclipse.aether.named.NamedLock` that is acquired from factory +`org.eclipse.aether.named.NamedLockFactory` for given "name". Two threads (or processes, depending on backing +implementation) that use same name can then coordinate each other by acquiring "shared" or "exclusive" access to +resource mapped to "name". Named locks tread "name" just as an opaque identifier, nothing more. The design attempts +for similarity with existing Java constructs like `ReentrantReadWriteLock` is, and have similar properties as well. + +Named locks properties: +* lock states are assigned to current threads, hence, even same instance of named lock can be used by multiple threads +* reentrant: named locks allow you to reacquire same (shared or exclusive) lock you already have +* lock downgrading: named locks allow "lock downgrading", but semantically this results in no-op (as thread already owns + exclusive lock) +* lock upgrading: is not support and implementations will "fail fast" (throw runtime exception) for code that attempts + to perform lock upgrade. If must, proposed alternative is [DCL](https://en.wikipedia.org/wiki/Double-checked_locking). +* interruption of acquisition: named locks support interruption during acquisition +* named locks can be JVM local only, host wide (file advisory locking) or even fully distributed (Hazelcast, Redisson). + Named locks provide support classes for implementations, and provide out of the box several lock and name mapper implementations. Following implementations are "local" (local to JVM) named lock implementations: From bd951b062935624995e512bb87909839c4595501 Mon Sep 17 00:00:00 2001 From: Tamas Cservenak Date: Tue, 20 Jun 2023 15:07:24 +0200 Subject: [PATCH 2/3] Extend --- maven-resolver-named-locks/src/site/markdown/index.md.vm | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/maven-resolver-named-locks/src/site/markdown/index.md.vm b/maven-resolver-named-locks/src/site/markdown/index.md.vm index feff7a8ca..33082aeff 100644 --- a/maven-resolver-named-locks/src/site/markdown/index.md.vm +++ b/maven-resolver-named-locks/src/site/markdown/index.md.vm @@ -24,10 +24,11 @@ resources that each can have unique ID assigned (i.e., file with an absolute pat then you can use named locks to make sure they are being protected from concurrent read and write actions. The building block for named locks is `org.eclipse.aether.named.NamedLock` that is acquired from factory -`org.eclipse.aether.named.NamedLockFactory` for given "name". Two threads (or processes, depending on backing -implementation) that use same name can then coordinate each other by acquiring "shared" or "exclusive" access to -resource mapped to "name". Named locks tread "name" just as an opaque identifier, nothing more. The design attempts -for similarity with existing Java constructs like `ReentrantReadWriteLock` is, and have similar properties as well. +`org.eclipse.aether.named.NamedLockFactory` for given "name". Two threads (or processes, or even distributed +processes, depending on backing implementation) that use same name can then coordinate each other by acquiring +"shared" or "exclusive" access to resource mapped to "name". Named locks tread "name" just as an opaque identifier, +nothing more. The design attempts for similarity with existing Java constructs like `ReentrantReadWriteLock` is, +and have similar properties as well. Named locks properties: * lock states are assigned to current threads, hence, even same instance of named lock can be used by multiple threads From d5c048ea3c8bc2f07aeba40a7804e6503cd01840 Mon Sep 17 00:00:00 2001 From: Tamas Cservenak Date: Tue, 20 Jun 2023 15:12:38 +0200 Subject: [PATCH 3/3] Typos, updates --- .../src/site/markdown/index.md.vm | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/maven-resolver-named-locks/src/site/markdown/index.md.vm b/maven-resolver-named-locks/src/site/markdown/index.md.vm index 33082aeff..c970e0d76 100644 --- a/maven-resolver-named-locks/src/site/markdown/index.md.vm +++ b/maven-resolver-named-locks/src/site/markdown/index.md.vm @@ -25,20 +25,23 @@ then you can use named locks to make sure they are being protected from concurre The building block for named locks is `org.eclipse.aether.named.NamedLock` that is acquired from factory `org.eclipse.aether.named.NamedLockFactory` for given "name". Two threads (or processes, or even distributed -processes, depending on backing implementation) that use same name can then coordinate each other by acquiring -"shared" or "exclusive" access to resource mapped to "name". Named locks tread "name" just as an opaque identifier, -nothing more. The design attempts for similarity with existing Java constructs like `ReentrantReadWriteLock` is, -and have similar properties as well. +processes, depending on backing implementation) that use same "name" can then coordinate each other by acquiring +"shared" or "exclusive" access to resource mapped to "name". Named locks treat "name" just as an opaque identifier. +The design attempts for similarity with existing Java constructs like `ReentrantReadWriteLock`, +and share similar properties as well. Named locks properties: -* lock states are assigned to current threads, hence, even same instance of named lock can be used by multiple threads -* reentrant: named locks allow you to reacquire same (shared or exclusive) lock you already have -* lock downgrading: named locks allow "lock downgrading", but semantically this results in no-op (as thread already owns - exclusive lock) -* lock upgrading: is not support and implementations will "fail fast" (throw runtime exception) for code that attempts - to perform lock upgrade. If must, proposed alternative is [DCL](https://en.wikipedia.org/wiki/Double-checked_locking). -* interruption of acquisition: named locks support interruption during acquisition -* named locks can be JVM local only, host wide (file advisory locking) or even fully distributed (Hazelcast, Redisson). +* Reentrant: named locks allow you to reacquire same (shared or exclusive) lock you already have. +* Lock downgrading: named locks allow "lock downgrading", but semantically this results in no-op (as thread already owns + exclusive lock). +* Lock upgrading: is not supported and implementations will "fail fast" (throw runtime exception) for code that attempts + to perform it. If required, proposed alternative is [DCL](https://en.wikipedia.org/wiki/Double-checked_locking). +* Interruption of acquisition: named locks support interruption during acquisition. + +Named locks special properties: +* Coordination happens on Thread level (always) and goes all way up to processes or distributed processes (backing + implementation dependant) +* Named locks can be JVM local only, host wide (file locking) or even fully distributed (Hazelcast, Redisson). Named locks provide support classes for implementations, and provide out of the box several lock and name mapper implementations.