powerliners 0.2.12

// vim:fileencoding=utf-8:noet
//! Port of `powerline/lib/inotify.py`.
//!
//! Upstream is a 185-line ctypes wrapper around Linux's `inotify(7)`
//! syscalls (`inotify_init1`, `inotify_add_watch`, `inotify_rm_watch`)
//! plus a per-instance polling loop. It exists so the higher-level
//! `lib/watcher/inotify.py` `INotifyFileWatcher` can avoid the
//! `pyinotify` dep.
//!
//! Rust port strategy: when the `inotify` Rust crate gets added as a
//! dependency, the real port will land. Until then we expose:
//!   - the `INotifyError` shape so dispatchers can `catch` it
//!   - `INotify` and `load_inotify` shims that always return
//!     `INotifyError`, causing the watcher dispatcher
//!     (`lib/watcher/__init__.py:51-56`) to fall through to the stat
//!     backend on every platform.
//!
//! Behavioural parity: macOS upstream raises `INotifyError("INotify
//! not available on OS X")` immediately (py:37); the stat fallback is
//! the default. Our stub matches that behaviour on every platform.

// from __future__ import (unicode_literals, division, absolute_import, print_function)  // py:2
// import sys                                       // py:4
// import os                                        // py:5
// import errno                                     // py:6
// import ctypes                                    // py:7
// import struct                                    // py:8
// from ctypes.util import find_library             // py:10
// from powerline.lib.encoding import get_preferred_file_name_encoding  // py:12

// py:15  __copyright__ = '2013, Kovid Goyal <kovid at kovidgoyal.net>'
// py:16  __docformat__ = 'restructuredtext en'

/// Port of `class INotifyError(Exception)` from
/// `powerline/lib/inotify.py:19`.
///
/// Raised by `load_inotify()` when inotify is unavailable. Callers
/// (the watcher dispatcher) catch this and fall back to stat-based
/// polling.
#[derive(Debug, Clone)]
pub struct INotifyError(pub String);

impl std::fmt::Display for INotifyError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "INotifyError: {}", self.0)
    }
}

impl std::error::Error for INotifyError {}

/// Port of `load_inotify()` from `powerline/lib/inotify.py:25`.
///
/// Initialize the inotify library.
///
/// Rust stub: always returns `Err(INotifyError)` so the watcher
/// dispatcher falls back to stat. Matches upstream's macOS branch
/// (py:37) behaviour on every platform.
pub fn load_inotify() -> Result<INotify, INotifyError> {
    // py:26  def load_inotify():
    // py:27  ''' Initialize the inotify library '''
    // py:28  global _inotify
    // py:29  if _inotify is None:
    // py:30  if hasattr(sys, 'getwindowsversion'):
    // py:31  # On windows abort before loading the C library. Windows has
    // py:32  # multiple, incompatible C runtimes, and we have no way of knowing
    // py:33  # if the one chosen by ctypes is compatible with the currently
    // py:34  # loaded one.
    // py:35  raise INotifyError('INotify not available on windows')
    // py:36  if sys.platform == 'darwin':
    // py:37  raise INotifyError('INotify not available on OS X')
    // py:38  if not hasattr(ctypes, 'c_ssize_t'):
    // py:39  raise INotifyError('You need python >= 2.7 to use inotify')
    // py:40  name = find_library('c')
    // py:41  if not name:
    // py:42  raise INotifyError('Cannot find C library')
    // py:43  libc = ctypes.CDLL(name, use_errno=True)
    // py:44  for function in ('inotify_add_watch', 'inotify_init1', 'inotify_rm_watch'):
    // py:45  if not hasattr(libc, function):
    // py:46  raise INotifyError('libc is too old')
    // py:48  prototype = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int, use_errno=True)
    // py:49  init1 = prototype(('inotify_init1', libc), ((1, 'flags', 0),))
    // py:52  prototype = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint32, use_errno=True)
    // py:53  add_watch = prototype(('inotify_add_watch', libc), (
    // py:54  (1, 'fd'), (1, 'pathname'), (1, 'mask')))
    // py:57  prototype = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int, ctypes.c_int, use_errno=True)
    // py:58  rm_watch = prototype(('inotify_rm_watch', libc), (
    // py:59  (1, 'fd'), (1, 'wd')))
    // py:62  prototype = ctypes.CFUNCTYPE(ctypes.c_ssize_t, ctypes.c_int, ctypes.c_void_p, ctypes.c_size_t, use_errno=True)
    // py:63  read = prototype(('read', libc), (
    // py:64  (1, 'fd'), (1, 'buf'), (1, 'count')))
    // py:65  _inotify = (init1, add_watch, rm_watch, read)
    // py:66  return _inotify
    Err(INotifyError(
        "INotify support not yet wired in the Rust port — using stat fallback".into(),
    ))
}

/// Port of `class INotify` from `powerline/lib/inotify.py` (the body
/// starts after `load_inotify` returns).
///
/// **Status:** opaque placeholder. The full class needs the `inotify`
/// crate; until then, no instance is ever constructed (`load_inotify`
/// always errors).
pub struct INotify {
    // Hide a zero-sized field so we can't accidentally construct one
    // without going through `load_inotify`.
    _private: (),
}

impl INotify {
    /// Port of `INotify.handle_error()` from
    /// `powerline/lib/inotify.py:133` — placeholder.
    pub fn handle_error(&self) -> Result<(), INotifyError> {
        // py:114  def __init__(self, cloexec=True, nonblock=True):
        // py:115  self._init1, self._add_watch, self._rm_watch, self._read = load_inotify()
        // py:116  flags = 0
        // py:117  if cloexec:
        // py:118  flags |= self.CLOEXEC
        // py:119  if nonblock:
        // py:120  flags |= self.NONBLOCK
        // py:121  self._inotify_fd = self._init1(flags)
        // py:122  if self._inotify_fd == -1:
        // py:123  raise INotifyError(os.strerror(ctypes.get_errno()))
        // py:125  self._buf = ctypes.create_string_buffer(5000)
        // py:126  self.fenc = get_preferred_file_name_encoding()
        // py:127  self.hdr = struct.Struct(b'iIII')
        // py:128  # We keep a reference to os to prevent it from being deleted
        // py:131  self.os = os
        // py:133  def handle_error(self):
        // py:134  eno = ctypes.get_errno()
        // py:135  extra = ''
        // py:136  if eno == errno.ENOSPC:
        // py:137  extra = 'You may need to increase the inotify limits on your system, via /proc/sys/fs/inotify/max_user_*'
        // py:138  raise OSError(eno, self.os.strerror(eno) + str(extra))
        Err(INotifyError("INotify stub".into()))
    }

    /// Port of `INotify.close()` from
    /// `powerline/lib/inotify.py:149`.
    pub fn close(&self) {
        // py:140  def __del__(self):
        // py:141  # This method can be called during interpreter shutdown, which means we
        // py:142  # must do the absolute minimum here. Note that there could be running
        // py:143  # daemon threads that are trying to call other methods on this object.
        // py:144  try:
        // py:145  self.os.close(self._inotify_fd)
        // py:146  except (AttributeError, TypeError):
        // py:147  pass
        // py:149  def close(self):
        // py:150  if hasattr(self, '_inotify_fd'):
        // py:151  self.os.close(self._inotify_fd)
        // py:152  del self.os
        // py:153  del self._add_watch
        // py:154  del self._rm_watch
        // py:155  del self._inotify_fd
    }

    /// Port of `INotify.read()` from
    /// `powerline/lib/inotify.py:157`.
    pub fn read(&self, _get_name: bool) -> Vec<(i32, u32, u32, Option<String>)> {
        // py:157  def read(self, get_name=True):
        // py:158  buf = []
        // py:159  while True:
        // py:160  num = self._read(self._inotify_fd, self._buf, len(self._buf))
        // py:161  if num == 0:
        // py:162  break
        // py:163  if num < 0:
        // py:164  en = ctypes.get_errno()
        // py:165  if en == errno.EAGAIN:
        // py:166  break  # No more data
        // py:167  if en == errno.EINTR:
        // py:168  continue  # Interrupted, try again
        // py:169  raise OSError(en, self.os.strerror(en))
        // py:170  buf.append(self._buf.raw[:num])
        // py:171  raw = b''.join(buf)
        // py:172  pos = 0
        // py:173  lraw = len(raw)
        // py:174  while lraw - pos >= self.hdr.size:
        // py:175  wd, mask, cookie, name_len = self.hdr.unpack_from(raw, pos)
        // py:176  pos += self.hdr.size
        // py:177  name = None
        // py:178  if get_name:
        // py:179  name = raw[pos:pos + name_len].rstrip(b'\0')
        // py:180  pos += name_len
        // py:181  self.process_event(wd, mask, cookie, name)
        Vec::new()
    }

    /// Port of `INotify.process_event()` from
    /// `powerline/lib/inotify.py:183` — raises NotImplementedError.
    pub fn process_event(&self, _wd: i32, _mask: u32, _cookie: u32, _name: Option<&str>) {
        // py:183  def process_event(self, *args):
        // py:184  raise NotImplementedError()
        unimplemented!("INotify.process_event must be overridden");
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn load_inotify_returns_error_in_stub() {
        let r = load_inotify();
        assert!(r.is_err());
    }

    #[test]
    fn inotify_error_implements_display() {
        let e = INotifyError("test".into());
        assert!(e.to_string().contains("INotifyError"));
        assert!(e.to_string().contains("test"));
    }
}