# oncer

A blazingly fast utility for running things once;

Have you had the problem of
- accidentally having multiple instances of your editor open, causing it to warn you about your files, or 
- have a start menu for your window manager, which doesn't close, when you hit the "Super"-key again, or
- it just being annoying to restart a debugging server?
.. then `oncer` is for you!


e.g. use `--do-nothing` for your editor, `--toggle` to toggle your start menu on and off and `--replace` to easily re-start your development server.


## Usage

```
oncer - A blazingly fast utility for running things once;

USAGE:
  oncer [OPTIONS] INPUT

FLAGS:
  -h, --help            Prints help information

OPTIONS:
  -d --do-nothing    [DEFAULT] Do nothing if process exists (and start if it doesn't)
  -t --toggle                  Toggle (kill process if it runs, start it if it doesn't)
  -r --replace                 Replace (kill process if it runs, always start a new one)

ARGS:
  <INPUT>               command or path to the executable to run

DISCLAIMER:
    This utility will KILL other running instances of the command to run.
    Please ensure you do not run this programm in a way that causes you to loose data!

    This utility is IN NO WAY for running programs, which require permanent supervision, 
    may loose/corrupt data or have security problems when ran multiple times.
    Please see the README for more information.
```

## Installation

```bash
cargo install oncer --locked
```

## Why not just use bash?

### Ease-of-Use

It is just simpler than having to remember or look up the required bash invocations all the time.

### Compatability

Some programs only accept commands, not full shell control-flow (e.g. the sway config)

### Performance 

`oncer` performs about twice as fast as the bash-oneliner one would usually write:

```bash
$ hyperfine "oncer true" "./oncer-bash true" -N
Benchmark 1: oncer true
  Time (mean ± σ):       4.9 ms ±   0.2 ms    [User: 1.3 ms, System: 3.5 ms]
  Range (min … max):     4.6 ms …   5.9 ms    512 runs

Benchmark 2: ./oncer-bash true
  Time (mean ± σ):      10.1 ms ±   0.2 ms    [User: 3.0 ms, System: 6.9 ms]
  Range (min … max):     9.4 ms …  11.0 ms    285 runs

Summary
  oncer true ran
    2.04 ± 0.08 times faster than ./oncer-bash true

```

The bash alternative used for benchmarking:

```bash
#!/bin/bash

PROGRAM=`which $1`
pidof -sq "$PROGRAM" && pkill -fx "$PROGRAM" || exec "$PROGRAM"
```

Other variants (like if/else or using the `dash` shell) saw no significant differences. 

Note: 
While this is of course significant difference, many uses will still be fine-enough when using the bash alternative.
This mostly makes a difference when starting a program, which is expected to take user input right afterwards.


## Important Disclaimer

DO NOT USE THIS UTILITY WITH PROGRAMS THAT 
- LOOSE/CORRUPT DATA IF RAN TWICE OR MORE
- SUFFER SECURITY PROBLEMS IF RAN TWICE OR MORE

The way this utility currently works is to first check whether the program is running and then perform an action.
This means there is a small window of time where two calls of this program could overlap and thus call the given subprogram or more times ("TOCTOU"). \*

Furthermore, this program does NOT protect from any process being started normally in the command-line.¸\*\*

All of this happens _rarely, if ever in normal usage_. 
(And in that case you could just close the spurious instance).

However, given an malevolent actor, this behavior can be provoked intentionally.

Thus: 
- Do NOT use this for e.g. restarting production databases or services like that (use systemd or something similar instead)!
- If the application you are using has security vulnerabilities when ran multiple times DO NOT use it with `oncer` (And please try to contact the author about it or if you are able fix it yourself.)


\* This problem could likely be mitigated using inter-process synchronization; 
It is unclear whether this is possible without a significant performance penalty;
Feel free to make contribute or make suggestions.

\*\* This is unfixable, as `oncer` has does not and should not have the wide-reaching permissions to do this;

## Contributing

Contributions are welcome. - Please just open an issue or a PR.

By offering your code to be integrated in this project, you agree to license it with this projects license.