Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.46.0

0.46.0 / src / support / changes.lucb

#==============================================================================================
#
#   changes - Whether anything in a directory changed, without looking at its files
#
#   DESCRIPTION:
#       A host that keeps checked modules (`embed.Library.check_file`) looks at every file
#       they were read from before each check (`stamps`). On macOS and Linux a look costs
#       under a microsecond a file; on Windows it costs 15 to 20, 4 ms for the 240 files of a
#       script importing luce-geocore. Windows can say instead whether a directory changed:
#       a change notification armed on it is signalled by the first change after it is
#       armed, and one wait that does not wait asks every armed notification at once, in a
#       few microseconds. The files are looked at only when one was signalled.
#
#       A notification holds its directory open, which keeps the directories above it from
#       being renamed while it is armed (the directory itself can still be renamed or
#       removed). Elsewhere nothing is armed, and every check looks at the files.
#
#==============================================================================================

import c
import platform

extern func FindFirstChangeNotificationA(path: c.str, subtree: i32, filter: u32) -> usize
extern func FindNextChangeNotification(handle: usize) -> i32
extern func FindCloseChangeNotification(handle: usize) -> i32
extern func WaitForMultipleObjects(count: u32, handles: const usize*, wait_all: i32, milliseconds: u32) -> u32
extern func WaitForSingleObject(handle: usize, milliseconds: u32) -> u32

# A file or directory made, renamed or removed, or a file's size or write time moved
# (`FILE_NOTIFY_CHANGE_FILE_NAME`, `_DIR_NAME`, `_SIZE`, `_LAST_WRITE`).
let file_name: u32 = 1
let directory_name: u32 = 2
let size: u32 = 8
let last_write: u32 = 16
# What a wait answers when nothing was signalled, and what a failed arming returns.
let wait_timeout: u32 = 258
let invalid_handle: usize = 18446744073709551615
# The most handles one wait takes (`MAXIMUM_WAIT_OBJECTS`).
let most_per_wait: usize = 64

## Whether the system says when a directory changed: on Windows; elsewhere no watch is
## ever armed.
pub func watching() -> bool:
    return platform.windows

## What a watch on a directory sees.
pub enum Reach as u8:
    ## A directory made, renamed or removed in it: the parent of a watched tree, whose own
    ## watch does not see the tree's directory renamed away.
    names = 1
    ## A file or directory in it made, renamed, removed or written; nothing below them.
    entries = 2
    ## Anything in it or below it.
    tree = 3

## A directory watched for changes. It is not armed where the system has no notifications
## or when arming failed, and then says nothing: the files are looked at.
pub struct Watch:
    ## The directory, NUL-terminated.
    pub var path: str
    ## What the watch sees.
    pub var reach: Reach
    ## The notification's handle; 0 when not armed.
    var handle: usize

    ## A watch on the directory at `path` (NUL-terminated) that sees `reach`. Arm it before
    ## looking at what it watches: a change after arming is seen, one before is not.
    pub static func arm(path: str, reach: Reach) -> Watch:
        var watch = Watch(path = path, reach = reach, handle = 0)
        if platform.windows:
            let filter = directory_name if reach == Reach.names else file_name | directory_name | size | last_write
            let handle = FindFirstChangeNotificationA((c.str)path, 1 if reach == Reach.tree else 0, filter)
            if handle != invalid_handle:
                watch.handle = handle
        return watch

    ## A watch that is never armed: a file that no directory speaks for.
    pub static func unarmed() -> Watch:
        return Watch(path = "", reach = Reach.names, handle = 0)

    ## Stop watching.
    pub func close():
        if platform.windows:
            if self.handle != 0:
                _ = FindCloseChangeNotification(self.handle)
        self.handle = 0

## Whether nothing changed in any of `watches` since it was armed or last looked at here.
## False when there are none, when one is not armed, or when one was signalled: then each
## signalled one is armed again before this returns, so a change made while the caller
## looks at the files is seen next time, and one that cannot be armed again is closed.
pub func quiet(watches: Watch[]) -> bool:
    if watches.length == 0 or not platform.windows:
        return false
    if signalled(watches):
        rearm(watches)
        return false
    return true

# Every call to the system below sits under `platform.windows`, so no other target's build
# refers to it.

## Whether any of `watches` was signalled, or is not armed.
func signalled(watches: Watch[]) -> bool:
    if platform.windows:
        var handles: usize[64]
        var start: usize = 0
        while start < watches.length:
            var count: usize = 0
            while count < most_per_wait and start + count < watches.length:
                let handle = watches[start + count].handle
                if handle == 0:
                    return true
                handles[count] = handle
                count += 1
            if WaitForMultipleObjects((u32)count, &handles[0], 0, 0) != wait_timeout:
                return true
            start += count
    return false

## Arm each signalled one of `watches` again; close one that cannot be.
func rearm(watches: Watch[]):
    if platform.windows:
        for i in 0..<watches.length:
            let handle = watches[i].handle
            if handle != 0 and WaitForSingleObject(handle, 0) != wait_timeout and FindNextChangeNotification(handle) == 0:
                watches[i].close()