package GNATCOLL.OS.Lock is
package UTF8 renames Ada.Strings.UTF_Encoding;
type Cross_Process_Lock is tagged limited private;
-- An exclusive lock. Two processes locking the same file exclude each
-- other. The lock is released by Unlock or by finalization of the object.
procedure Lock
(Self : in out Cross_Process_Lock;
Path : UTF8.UTF_8_String;
Retry_Delay : Duration := 1.0);
-- Acquire the lock on the file at Path, creating it if needed; if Self
-- already holds a lock it is released first. Blocks indefinitely until
-- the lock is acquired.
--
-- Retry_Delay is ignored on Unix, where the process blocks in the kernel;
-- on Windows, which cannot block, it is the interval between polls.
--
-- Raises OS_Error if the lock file cannot be created or opened.
function Try_Lock
(Self : in out Cross_Process_Lock;
Path : UTF8.UTF_8_String;
Retry_Delay : Duration := 1.0;
Retries : Natural := 0) return Boolean;
-- Acquire the lock on the file at Path, creating it if needed; if Self
-- already holds a lock it is released first.
--
-- One attempt is made immediately. If the lock is held elsewhere, Try_Lock
-- retries every Retry_Delay seconds, up to Retries times (so for up to
-- Retry_Delay * Retries seconds). The default Retries => 0 makes a single,
-- non-blocking attempt.
--
-- Return True if the lock was acquired, False otherwise.
-- Raises OS_Error if the lock file cannot be created or opened.
procedure Unlock (Self : in out Cross_Process_Lock);
-- Release the lock. Has no effect if Self does not hold a lock.
--
-- The lock file is left in place; it is never deleted. Removing it while
-- another process holds or waits on the lock could let two processes lock
-- different files under the same name.
function Is_Locked (Self : Cross_Process_Lock) return Boolean;
-- Return True if Self currently holds the lock.
end GNATCOLL.OS.Lock;