io.github.hcoona:native-named-mutex

Cross platform named mutex which provide a system-wide mutex synchronization primitive

License	MIT License
Categories	Native Development Tools
GroupId	io.github.hcoona
ArtifactId	native-named-mutex
Last Version	1.3.0
Release Date	Apr 6, 2017
Type	jar
Description	io.github.hcoona:native-named-mutex Cross platform named mutex which provide a system-wide mutex synchronization primitive
Project URL	https://github.com/hcoona/native-named-mutex/
Source Code Management	https://github.com/hcoona/native-named-mutex/tree/master

Download native-named-mutex

Filename	Size
native-named-mutex-1.3.0.pom
native-named-mutex-1.3.0.jar	30 KB
native-named-mutex-1.3.0-sources.jar	18 KB
native-named-mutex-1.3.0-javadoc.jar	73 KB

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/io.github.hcoona/native-named-mutex/ -->
<dependency>
    <groupId>io.github.hcoona</groupId>
    <artifactId>native-named-mutex</artifactId>
    <version>1.3.0</version>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/io.github.hcoona/native-named-mutex/
implementation 'io.github.hcoona:native-named-mutex:1.3.0'

Gradle Kotlin

// https://jarcasting.com/artifacts/io.github.hcoona/native-named-mutex/
implementation ("io.github.hcoona:native-named-mutex:1.3.0")

Apache Buildr

'io.github.hcoona:native-named-mutex:jar:1.3.0'

Apache Ivy

<dependency org="io.github.hcoona" name="native-named-mutex" rev="1.3.0">
  <artifact name="native-named-mutex" type="jar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='io.github.hcoona', module='native-named-mutex', version='1.3.0')
)

Scala SBT

libraryDependencies += "io.github.hcoona" % "native-named-mutex" % "1.3.0"

Leiningen

[io.github.hcoona/native-named-mutex "1.3.0"]

Dependencies

compile (3)

Group / Artifact	Type	Version
net.java.dev.jna : jna	jar	4.3.0
net.java.dev.jna : jna-platform	jar	4.3.0
com.google.guava : guava	jar	21.0

test (2)

Group / Artifact	Type	Version
junit : junit	jar	4.12
org.apache.commons : commons-exec	jar	1.3

Project Modules

There are no modules declared in this project.

native-named-mutex

This is a Java library to provide a cross-platform system-wide named mutex synchronization primitive. It could be used for inter-process synchronization.

Moved to https://github.com/hcoona/one/tree/master/native-named-mutex

<dependency>
    <groupId>io.github.hcoona</groupId>
    <artifactId>native-named-mutex</artifactId>
    <version>1.3.0</version>
</dependency>

Underlying

It underlying use system API to implement Mutex.

Windows	Use CreateMutex API to create or open a named mutex object.
Linux	Use named semaphore in pthread to simulate a mutex.
Other	Use Java FileLock and ReentrantLock to simulate a mutex.

Future plan

Notice that macOS is supported in Other platform because macOS does not implement all posix semaphores API, especially sem_timedwait.

It is possible to leverage the Posix robust mutex with shared memory for more reliability in the future, so please NOT assume it always use semaphore on Linux. (See discussion here for more details)

Usage

Singleton your service in system-wide

You somehow might have to ensure there is only 1 instance running in your system. This is specially useful in enterprise services.

public static void main(String[] args) {
    final String mutexName = "/UniqueNameForYourService";
    try (NamedMutex mutex = NamedMutex.newInstance(true, mutexName)) {
        mutex.waitOne();
        Service service = createYourService();
        service.run();
    }
}

Wait with a timeout limit is also supported.

public static void main(String[] args) {
    final String mutexName = "/UniqueNameForYourService";
    try (NamedMutex mutex = NamedMutex.newInstance(true, mutexName)) {
        if (mutex.waitOne(5, TimeUnit.SECONDS)) {
            Service service = createYourService();
            service.run();
        } else {
            System.err.println("Cannot startup because there is another instance already running.");
        }
    }
}

Protect system-wide resources

You might need to run 2 apps but they have to use same TCP port some time.

try (NamedMutex mutex = NamedMutex.newInstance(true, "/Port_3386")) {
    mutex.waitOne();
    HttpListener listener = new HttpListener("0.0.0.0", 3386);
}

Synchronization between processes

You might need to synchronize between processes.

try (NamedMutex mutex = NamedMutex.newInstance(false, "/ProtectedSharedFileName")) {
    mutex.waitOne();
    writeSharedFile();
}

Versions

Version
1.3.0 Apr 6, 2017
1.2.0 Apr 5, 2017
1.1.0 Mar 23, 2017
1.0.0 Mar 19, 2017