docs: add examples module, update doc and publish 0.0.7-GA

CONTRIBUTING.md

@@ -4,11 +4,11 @@ Hi there! We're thrilled that you'd like to contribute to this project. Your hel
 
 ## Submitting a pull request
 
-1. [Fork][fork] and clone the repository
+1. Fork and clone the repository
 2. Create a new branch: `git checkout -b my-branch-name`
 3. Make your change and remember to add tests
 4. Build the project locally and run local tests
-5. Push to your fork and [submit a pull request][pr]
+5. Push to your fork and submit a pull request
 6. Pat your self on the back and wait for your pull request to be reviewed and merged.
 
 Thanks for your contributing!

README.md

@@ -1,60 +1,121 @@
-# DistributedLock
+# Halo-DistributedLock
 
-![Build](https://img.shields.io/github/actions/workflow/status/hellooo-stack/hellooo-distributedlock/maven.yml)
-![Code Size](https://img.shields.io/github/languages/code-size/hellooo-stack/hellooo-distributedlock)
-![Maven Central](https://img.shields.io/maven-central/v/site.hellooo/hellooo-distributedlock)
-![GitHub license](https://img.shields.io/github/license/hellooo-stack/hellooo-distributedlock)
-
-DistributedLock is a lightweight distributed lock framework that provides reliable consistency features. It can be used with only the Lock interface.
+![Build](https://img.shields.io/github/actions/workflow/status/hellooo-stack/halo-distributedlock/maven.yml)
+![Code Size](https://img.shields.io/github/languages/code-size/hellooo-stack/halo-distributedlock)
+![Maven Central](https://img.shields.io/maven-central/v/site.hellooo/halo-distributedlock)
+![GitHub license](https://img.shields.io/github/license/hellooo-stack/halo-distributedlock)
 
+halo-distributedlock is a simple and reliable distributed lock implementation. 
+It is designed to help you learn the principles of distributed locking 
+and provides a lightweight solution for your production environment (assuming you are using single instance Redis). 
+Whether you're a beginner or an experienced developer, It's worth to take a look at.
 
 # Features
-- Reentrant distributed locking
-- Supports tryLock(), lock(), unlock() operations
-- Supports lock leasing
+- Supports distributed lock, distributed unlock operations with a singleton Redis.
+- Supports lock leasing, lock blocking and lock reentrant.
 
 # Quick Start
 Step one: Add maven dependency
 ```xml
 <dependency>
     <groupId>site.hellooo</groupId>
-    <artifactId>hellooo-distributedlock</artifactId>
-    <version>>${hellooo-distributedlock.version}</version>
+    <artifactId>halo-distributedlock-core</artifactId>
+    <version>>${halo-distributedlock.version}</version>
 </dependency>
 ```
 
 Step two: lock your resources with Lock.lock()
 ```java
-public class Main {
+public class SingleProcessMultiThreadContention {
     public static void main(String[] args) {
-        LockOptions lockOptions = LockOptions.options()
-                .build();
+        lockCompetition();
+    }
+
+    public static void lockCompetition() {
+        long start = System.currentTimeMillis();
+
+        ConfigReader.RedisConfig redisConfig = ConfigReader.redis();
+        String host = redisConfig.getHost();
+        int port = redisConfig.getPort();
 
-//        define the redis source
-        JedisPool pool = new JedisPool("localhost", 6379);
-        for (int i = 0; i < 10; i++) {
+        JedisPool jedisPool = new JedisPool(host, port);
+        for (int i = 0; i < 500; i++) {
             final int threadNumber = i;
             Thread thread = new Thread(() -> {
-                Thread.currentThread().setName("Thread " + threadNumber);
-
-                try (Jedis jedis = pool.getResource()) {
-                    try {
-                        Lock lock = new ReentrantDistributedLock(lockOptions, "my_lock", new RedisLockHandler(jedis));
-//                        lock 
-                        lock.lock();
-                        System.out.println("thread" + Thread.currentThread().getName() + " locked!");
-                        Thread.sleep(1000);
-                        System.out.println("thread" + Thread.currentThread().getName() + " lock released!");
-//                        unlock
-                        lock.unlock();
-                    } catch (Exception e) {
-                        e.printStackTrace();
-                    }
-                }
+                Thread.currentThread().setName("locking_thread_" + threadNumber);
+
+                Lock lock = new ReentrantDistributedLockBuilder()
+                        .lockOptions(LockOptions.ofDefault())
+                        .jedisPool(jedisPool)
+                        .lockTarget("my_lock")
+                        .build();
+
+                System.out.println("process [" + ProcessUtils.getProcessId() + "] thread [" + Thread.currentThread().getName() + "] is getting lock");
+                lock.lock();
+                System.out.println("process [" + ProcessUtils.getProcessId() + "] thread [" + Thread.currentThread().getName() + "] got lock");
+                lock.unlock();
+                System.out.println("process [" + ProcessUtils.getProcessId() + "] thread [" + Thread.currentThread().getName() + "] released lock");
             });
             thread.start();
         }
+
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            jedisPool.close();
+            System.out.println("cause: " + (System.currentTimeMillis() - start) + "ms");
+        }));
     }
 }
+```
+
+# Examples
+You can find some examples in the [examples](https://github.com/hellooo-stack/halo-distributedlock/tree/master/examples) module. 
+If you want to simulate multiple-process, multiple-thread competition, you should run multiprocess/Step0, 
+and then run multiprocess/Step1 within a 5-second window. You will see the result like this:
+```
+# process1:
+# process [99991] thread [locking_thread_0] is getting lock
+# process [99991] thread [locking_thread_8] is getting lock
+# process [99991] thread [locking_thread_7] is getting lock
+# process [99991] thread [locking_thread_6] is getting lock
+# process [99991] thread [locking_thread_2] is getting lock
+# process [99991] thread [locking_thread_5] is getting lock
+# process [99991] thread [locking_thread_4] is getting lock
+# process [99991] thread [locking_thread_3] is getting lock
+# process [99991] thread [locking_thread_9] is getting lock
+# process [99991] thread [locking_thread_1] is getting lock
+# process [99991] thread [locking_thread_8] got lock
+# process [99991] thread [locking_thread_8] released lock
+# process [99991] thread [locking_thread_7] got lock
+# process [99991] thread [locking_thread_7] released lock
+# process [99991] thread [locking_thread_3] got lock
+# process [99991] thread [locking_thread_3] released lock
+# process [99991] thread [locking_thread_0] got lock
+# process [99991] thread [locking_thread_0] released lock
+# process [99991] thread [locking_thread_9] got lock
+# process [99991] thread [locking_thread_9] released lock
+# process [99991] thread [locking_thread_2] got lock
+# process [99991] thread [locking_thread_2] released lock
+# ...
 
+
+# process2:
+# process [96469] thread [locking_thread_498] is getting lock
+# process [96469] thread [locking_thread_499] is getting lock
+# process [96469] thread [locking_thread_152] got lock
+# process [96469] thread [locking_thread_152] released lock
+# process [96469] thread [locking_thread_139] got lock
+# process [96469] thread [locking_thread_139] released lock
+# process [96469] thread [locking_thread_417] got lock
+# process [96469] thread [locking_thread_417] released lock
+# process [96469] thread [locking_thread_213] got lock
+# process [96469] thread [locking_thread_213] released lock
+# process [96469] thread [locking_thread_458] got lock
+# process [96469] thread [locking_thread_458] released lock
+# process [96469] thread [locking_thread_124] got lock
+# process [96469] thread [locking_thread_124] released lock
+# process [96469] thread [locking_thread_204] got lock
+# process [96469] thread [locking_thread_204] released lock
+# ...
 ```
+
+

core/pom.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>site.hellooo</groupId>
+        <artifactId>halo-distributedlock</artifactId>
+        <version>${revision}</version>
+    </parent>
+
+    <artifactId>halo-distributedlock-core</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>redis.clients</groupId>
+            <artifactId>jedis</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+        </dependency>
+    </dependencies>
+</project>

core/src/main/java/site/hellooo/distributedlock/core/DistributedLock.java

@@ -0,0 +1,13 @@
+package site.hellooo.distributedlock.core;
+
+import site.hellooo.distributedlock.core.enums.Coordinator;
+import site.hellooo.distributedlock.core.enums.LockType;
+
+import java.util.concurrent.locks.Lock;
+
+public interface DistributedLock extends Lock {
+
+    LockType lockType();
+
+    Coordinator coordinatorType();
+}

src/main/java/site/hellooo/distributedlock/LockCallback.java → core/src/main/java/site/hellooo/distributedlock/core/LockCallback.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock;
+package site.hellooo.distributedlock.core;
 
 public interface LockCallback {
     // execute immediately after the lock granted to current thread

src/main/java/site/hellooo/distributedlock/LockContext.java → core/src/main/java/site/hellooo/distributedlock/core/LockContext.java

@@ -1,6 +1,6 @@
-package site.hellooo.distributedlock;
+package site.hellooo.distributedlock.core;
 
-import site.hellooo.distributedlock.config.LockOptions;
+import site.hellooo.distributedlock.core.config.LockOptions;
 
 import java.util.concurrent.atomic.AtomicReference;
 

src/main/java/site/hellooo/distributedlock/LockHandler.java → core/src/main/java/site/hellooo/distributedlock/core/LockHandler.java

@@ -1,10 +1,10 @@
-package site.hellooo.distributedlock;
+package site.hellooo.distributedlock.core;
 
-import site.hellooo.distributedlock.enums.Coordinator;
-import site.hellooo.distributedlock.exception.LockStateNotRemovedException;
-import site.hellooo.distributedlock.exception.LockStateNotSetException;
-import site.hellooo.distributedlock.exception.LockStateRemoveExpiredException;
-import site.hellooo.distributedlock.exception.LockStateSetExpiredException;
+import site.hellooo.distributedlock.core.enums.Coordinator;
+import site.hellooo.distributedlock.core.exception.LockStateNotRemovedException;
+import site.hellooo.distributedlock.core.exception.LockStateNotSetException;
+import site.hellooo.distributedlock.core.exception.LockStateRemoveExpiredException;
+import site.hellooo.distributedlock.core.exception.LockStateSetExpiredException;
 
 public interface LockHandler {
 

src/main/java/site/hellooo/distributedlock/LockState.java → core/src/main/java/site/hellooo/distributedlock/core/LockState.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock;
+package site.hellooo.distributedlock.core;
 
 import java.io.Serializable;
 

src/main/java/site/hellooo/distributedlock/Reusable.java → core/src/main/java/site/hellooo/distributedlock/core/Reusable.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock;
+package site.hellooo.distributedlock.core;
 
 public interface Reusable<T> {
     T copy();

src/main/java/site/hellooo/distributedlock/common/ArgChecker.java → core/src/main/java/site/hellooo/distributedlock/core/common/ArgChecker.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.common;
+package site.hellooo.distributedlock.core.common;
 
 public final class ArgChecker {
     public static void check(boolean predicate) {

src/main/java/site/hellooo/distributedlock/common/ClassUtils.java → core/src/main/java/site/hellooo/distributedlock/core/common/ClassUtils.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.common;
+package site.hellooo.distributedlock.core.common;
 
 public class ClassUtils {
     public static <O> String getObjClassName(O object) {

src/main/java/site/hellooo/distributedlock/common/NetworkUtils.java → core/src/main/java/site/hellooo/distributedlock/core/common/NetworkUtils.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.common;
+package site.hellooo.distributedlock.core.common;
 
 import java.net.InetAddress;
 import java.net.UnknownHostException;

src/main/java/site/hellooo/distributedlock/common/ProcessUtils.java → core/src/main/java/site/hellooo/distributedlock/core/common/ProcessUtils.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.common;
+package site.hellooo.distributedlock.core.common;
 
 import java.lang.management.ManagementFactory;
 

src/main/java/site/hellooo/distributedlock/common/StringUtils.java → core/src/main/java/site/hellooo/distributedlock/core/common/StringUtils.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.common;
+package site.hellooo.distributedlock.core.common;
 
 public class StringUtils {
     public static String empty() {

src/main/java/site/hellooo/distributedlock/config/LockOptions.java → core/src/main/java/site/hellooo/distributedlock/core/config/LockOptions.java

@@ -1,8 +1,8 @@
-package site.hellooo.distributedlock.config;
+package site.hellooo.distributedlock.core.config;
 
-import site.hellooo.distributedlock.Reusable;
-import site.hellooo.distributedlock.common.ArgChecker;
-import site.hellooo.distributedlock.enums.Coordinator;
+import site.hellooo.distributedlock.core.Reusable;
+import site.hellooo.distributedlock.core.common.ArgChecker;
+import site.hellooo.distributedlock.core.enums.Coordinator;
 
 import java.io.Serializable;
 import java.util.StringJoiner;

src/main/java/site/hellooo/distributedlock/enums/Coordinator.java → core/src/main/java/site/hellooo/distributedlock/core/enums/Coordinator.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.enums;
+package site.hellooo.distributedlock.core.enums;
 
 public enum Coordinator {
 

src/main/java/site/hellooo/distributedlock/enums/LockType.java → core/src/main/java/site/hellooo/distributedlock/core/enums/LockType.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.enums;
+package site.hellooo.distributedlock.core.enums;
 
 public enum LockType {
 

src/main/java/site/hellooo/distributedlock/exception/BuilderEssentialFieldNotSetException.java → core/src/main/java/site/hellooo/distributedlock/core/exception/BuilderEssentialFieldNotSetException.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.exception;
+package site.hellooo.distributedlock.core.exception;
 
 public class BuilderEssentialFieldNotSetException extends RuntimeException {
     public BuilderEssentialFieldNotSetException() {

src/main/java/site/hellooo/distributedlock/exception/GenericRuntimeLockException.java → core/src/main/java/site/hellooo/distributedlock/core/exception/GenericRuntimeLockException.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.exception;
+package site.hellooo.distributedlock.core.exception;
 
 public class GenericRuntimeLockException extends RuntimeException {
     public GenericRuntimeLockException() {

src/main/java/site/hellooo/distributedlock/exception/LockStateNotRemovedException.java → core/src/main/java/site/hellooo/distributedlock/core/exception/LockStateNotRemovedException.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.exception;
+package site.hellooo.distributedlock.core.exception;
 
 import java.io.IOException;
 

src/main/java/site/hellooo/distributedlock/exception/LockStateNotSetException.java → core/src/main/java/site/hellooo/distributedlock/core/exception/LockStateNotSetException.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.exception;
+package site.hellooo.distributedlock.core.exception;
 
 import java.io.IOException;
 

src/main/java/site/hellooo/distributedlock/exception/LockStateRemoveExpiredException.java → core/src/main/java/site/hellooo/distributedlock/core/exception/LockStateRemoveExpiredException.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.exception;
+package site.hellooo.distributedlock.core.exception;
 
 import java.io.IOException;
 

src/main/java/site/hellooo/distributedlock/exception/LockStateSetExpiredException.java → core/src/main/java/site/hellooo/distributedlock/core/exception/LockStateSetExpiredException.java

@@ -1,4 +1,4 @@
-package site.hellooo.distributedlock.exception;
+package site.hellooo.distributedlock.core.exception;
 
 import java.io.IOException;
 

src/main/java/site/hellooo/distributedlock/impl/AbstractDistributedLock.java → core/src/main/java/site/hellooo/distributedlock/core/impl/AbstractDistributedLock.java

@@ -1,6 +1,6 @@
-package site.hellooo.distributedlock.impl;
+package site.hellooo.distributedlock.core.impl;
 
-import site.hellooo.distributedlock.DistributedLock;
+import site.hellooo.distributedlock.core.DistributedLock;
 
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.locks.Condition;

src/main/java/site/hellooo/distributedlock/impl/LockCallbackFactory.java → core/src/main/java/site/hellooo/distributedlock/core/impl/LockCallbackFactory.java

@@ -1,9 +1,9 @@
-package site.hellooo.distributedlock.impl;
+package site.hellooo.distributedlock.core.impl;
 
-import site.hellooo.distributedlock.LockCallback;
-import site.hellooo.distributedlock.LockContext;
-import site.hellooo.distributedlock.enums.Coordinator;
-import site.hellooo.distributedlock.impl.redis.RedisLockCallback;
+import site.hellooo.distributedlock.core.LockCallback;
+import site.hellooo.distributedlock.core.LockContext;
+import site.hellooo.distributedlock.core.enums.Coordinator;
+import site.hellooo.distributedlock.core.impl.redis.RedisLockCallback;
 
 public class LockCallbackFactory {
     public static LockCallback of(Coordinator coordinator, LockContext lockContext) {

src/main/java/site/hellooo/distributedlock/impl/LockStateBuilder.java → core/src/main/java/site/hellooo/distributedlock/core/impl/LockStateBuilder.java

@@ -1,12 +1,12 @@
-package site.hellooo.distributedlock.impl;
+package site.hellooo.distributedlock.core.impl;
 
 
-import site.hellooo.distributedlock.LockState;
-import site.hellooo.distributedlock.common.ArgChecker;
-import site.hellooo.distributedlock.common.StringUtils;
-import site.hellooo.distributedlock.config.LockOptions;
-import site.hellooo.distributedlock.enums.Coordinator;
-import site.hellooo.distributedlock.impl.redis.RedisLockState;
+import site.hellooo.distributedlock.core.LockState;
+import site.hellooo.distributedlock.core.common.ArgChecker;
+import site.hellooo.distributedlock.core.common.StringUtils;
+import site.hellooo.distributedlock.core.config.LockOptions;
+import site.hellooo.distributedlock.core.enums.Coordinator;
+import site.hellooo.distributedlock.core.impl.redis.RedisLockState;
 
 public class LockStateBuilder {