This is an automated email from the ASF dual-hosted git repository.
cstamas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-resolver.git
The following commit(s) were added to refs/heads/master by this push:
new 30e1cb63 Extend NamedLocks doco (#304)
30e1cb63 is described below
commit 30e1cb633270684c4a8c4fbcc85bd46c0256b6b4
Author: Tamas Cservenak <[email protected]>
AuthorDate: Tue Jun 20 15:25:49 2023 +0200
Extend NamedLocks doco (#304)
Add a bit more explaining how they work.
---
.../src/site/markdown/index.md.vm | 20 ++++++++++++++++++++
1 file changed, 20 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 17486e77..c970e0d7 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,26 @@ 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, 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 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:
+* 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.
Following implementations are "local" (local to JVM) named lock
implementations:
