[−][src]Crate namaste
Namaste
Project
- Repository: https://bitbucket.org/haibison/namaste-rs
- License: Free Public License 1.0.0
- This project follows Semantic Versioning 2.0.0
Features
- Handling locks amongst processes via TCP.
Design
Unique identifier
A unique identifier (UID) is a 64-byte array, which matches an SHA3-512 hash.
Server and client
-
Server starts on a fixed TCP port, and listens for clients.
-
When a new client connects to, they are expected to send 3 pieces of information:
- Global UID. This UID is used within a lifetime of the server, as an identification of the client.
- Handshake UID. This UID is used for the server to communicate with client.
- Client's local TCP server port, consisting of 2 bytes, in big-endian order.
-
Server then connects to the client's local server, sends the handshake UID, reads a UID and compares it with the first one above.
-
If the verification passes, server stores client UID in memory, and sends back one non-zero byte to client.
-
If the verification does not passes, server sends back one zero byte to client.
Usage
- You should only rely on this library for limited small amount of locks between your program's processes. For instance, this library can help with single-instance designed programs.
- Client side will ask system to grant it a random TCP server port. On most systems, TCP ports are limited. So it's highly recommended that you should not rely too much on this library (client side).
FAQ
Why not Unix Domain Socket?
UDS has a good design, but its implementation has some serious flaws:
- Already-bound file path can be deleted. Any new binding to that path will silently take control of current one.
- Linux has an extension to UDS, which is called abstract sockets. Its design is very good, and can totally replace this library. However its documentation clearly states that it is not portable.
Why not file locks?
- On Unix, locked files can still be deleted.
Examples
use namaste::{Uid, client, server}; // It is expected that the system _already_ has Namaste server running! const UID: Uid = [...]; const HANDSHAKE_UID: Uid = [...]; fn main() { match client::book(UID, HANDSHAKE_UID, server::DEFAULT_PORT, namaste::DEFAULT_RW_TIMEOUT) { Ok(true) => run_main_job(), Ok(false) => eprintln!("Another instance is running"), Err(err) => eprintln!("Failed connecting to Namaste server: {}", err), }; }
Modules
client | Client |
server | Server |
version_info |
|
Constants
CODE_NAME | Crate code name |
DEFAULT_IP | Default IP address, used for both server and client |
DEFAULT_RW_TIMEOUT | Default read/write timeout: 3 seconds |
NAME | Crate name |
RELEASE_DATE | Crate release date (year/month/day) |
TAG | Tag, which can be used for logging... |
UUID | Unique universally identifier of this crate |
VERSION | Crate version |
Functions
cmp_uids | Compares UIDs |
read_uid | Reads UID |
Type Definitions
Uid | Unique ID |