pidfile

Documentation

Overview

Package pidfile manages VORTEX's PID file: a small text file holding the running server's process ID. It is used to coordinate the start/stop/status/ reload CLI commands and to prevent two servers from running against the same pidfile.

Writing is stale-lock aware: if the pidfile already names a process that is still alive, Write refuses; if it names a dead process (a stale lock left by a crash), Write silently takes over. Liveness probing is implemented per-OS (see pidfile_unix.go / pidfile_windows.go) so it works on both.

Index

• func IsRunning(path string) (bool, int, error)
• func Read(path string) (int, error)
• func Remove(path string) error
• func Write(path string) error
• type FileLock
  • func Lock(path string) (*FileLock, error)
  • func WriteLocked(path string) (*FileLock, error)
  • func (l *FileLock) Unlock() error

Functions

func IsRunning

func IsRunning(path string) (bool, int, error)

IsRunning reports whether the process named by the pidfile at path is alive. It returns (alive, pid, err). A missing pidfile is reported as (false, 0, os.ErrNotExist).

func Read

func Read(path string) (int, error)

Read returns the PID recorded in the file at path. If the file does not exist it returns os.ErrNotExist.

func Remove

func Remove(path string) error

Remove deletes the pidfile. It is idempotent: a missing file is not an error.

func Write

func Write(path string) error

Write records the current process ID in the file at path, creating parent directories as needed. Creation is atomic via O_CREATE|O_EXCL, eliminating the check-then-write race: if the file already exists, Write inspects the PID inside it. If that process is alive, Write returns an error naming the PID; if it is dead (a stale lock from a crash), the stale file is removed and the write is retried once.

Types

type FileLock

type FileLock struct {
	// contains filtered or unexported fields
}

FileLock is an advisory exclusive lock held on a lock file adjacent to the pidfile. It prevents two `vortex start` processes from racing to claim the same pidfile. Release it with Unlock. (Named FileLock rather than Lock so the Lock acquisition function can keep that name.)

func Lock

func Lock(path string) (*FileLock, error)

Lock acquires an exclusive lock keyed to the pidfile at path. The underlying mechanism is OS-specific (flock on Unix, exclusive open on Windows). It blocks behavior is non-blocking: if another process holds the lock, it returns an error rather than waiting.

func WriteLocked

func WriteLocked(path string) (*FileLock, error)

WriteLocked acquires the exclusive lock and then writes the pidfile while holding it, so the check-and-write is atomic against other processes. The returned Lock must be released by the caller (typically with defer lock.Unlock()) when the server shuts down.

func (*FileLock) Unlock

func (l *FileLock) Unlock() error

Unlock releases the lock and removes the lock file. It is safe to call once.