initial commit

.gitignore

@@ -0,0 +1,39 @@
+.gradle
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### IntelliJ IDEA ###
+/.idea/
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+bin/
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 iamcalledrob
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,63 @@
+# singleinstance
+
+## Introduction
+Lightweight Kotlin/JVM library that prevents multiple concurrent instances of a Kotlin application.
+Launch arguments from subsequent instances are communicated back to the first instance via a UNIX domain socket.
+
+A Kotlin equivalent to [unique4j](https://github.com/prat-man/unique4j)
+
+## Installation
+Add the [jitpack](https://jitpack.io/) repository to your build file:
+```kotlin
+repositories {
+    maven { url 'https://jitpack.io' }
+}
+```
+
+Then add as a module dependency:
+```kotlin
+dependencies {
+    implementation("com.github.iamcalledrob:singleinstance:1.0.0")
+}
+```
+
+## Usage
+Instantiate `SingleInstance` with a file path and call `args()`.
+1. If this is the first instance, `args` will listen indefinitely for subsequent instances to connect to it. 
+2. If there is an existing instance, `args` will connect and send its arguments, then exit.
+
+```kotlin
+fun main(args: Array<String>) {
+    SingleInstance("/path/to/a/unique/file.sock").args(args) { receivedArgs ->
+        // Handle received args from another instance
+        println("Subsequent instance args: ${receivedArgs.joinToString()}")
+    }
+
+    // Handle original args
+    println("Original launch args: ${args.joinToString()}")
+
+    // The rest of the application logic
+}
+```
+
+There is also a helper function for generating a suitable sock file path from an identifier:
+```kotlin
+socketPath(identifier = "org.foo.widget")
+// -> /tmp/org.foo.widget.sock
+```
+
+## How it works
+1. A system-wide file lock is used to determine which instance is "first" to launch
+2. The first instance then listens on a domain socket for arguments from other instances
+3. Other instances are unable to acquire the file lock, and instead connect to the first instance via the socket.
+   Arguments are written to the socket, then the process exits.
+4. When the original process exits, the file lock is released.
+
+## Why you might consider this over [unique4j](https://github.com/prat-man/unique4j)
+1. Uses [UNIX Domain Sockets](https://inside.java/2021/02/03/jep380-unix-domain-sockets-channels/), which avoids
+   triggering the Windows firewall. unique4j listens on a local TCP socket, which will pop a firewall dialog.
+2. Minimal design, leaves the exact implementation up to you.
+3. Filesystem permissions can be used to control which processes are able to send arguments, if desired.
+
+## Considerations
+Domain sockets were added to Windows version 1809, so this library is unsuitable for legacy versions of Windows.

build.gradle.kts

@@ -0,0 +1,31 @@
+plugins {
+    kotlin("jvm") version "1.9.23"
+    id("maven-publish")
+}
+
+group = "com.github.iamcalledrob"
+version = "1.0.0"
+
+repositories {
+    mavenCentral()
+}
+
+java {
+    withSourcesJar()
+}
+
+kotlin {
+    jvmToolchain(17)
+
+    dependencies {
+        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")
+    }
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("maven") {
+            from(components["java"])
+        }
+    }
+}

gradle.properties

@@ -0,0 +1 @@
+kotlin.code.style=official

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+#Tue Aug 06 11:36:36 BST 2024
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists