Trait IpcPort

Source
pub trait IpcPort: Send + Sync {
    // Required methods
    fn reload_theme(&self, theme: &Theme) -> Result<()>;
    fn send_command(&self, command: &str) -> Result<()>;
    fn is_shell_running(&self) -> bool;
    fn shell_version(&self) -> Option<String>;
    fn ping(&self) -> Result<u64>;
}
Expand description

Port for inter-process communication with QuickShell.

IpcPort provides communication between fernctl and the running QuickShell instance. This enables:

  • Live theme reloading without restarting the shell
  • Querying current shell state
  • Sending commands to the shell

§Communication Protocol

The default implementation uses D-Bus for IPC:

fernctl                           QuickShell
  │                                   │
  │    D-Bus: org.fern.Shell          │
  │ ───────────────────────────────►  │
  │    Method: ReloadTheme            │
  │    Params: { path: "..." }        │
  │                                   │
  │    Response: { success: true }    │
  │ ◄───────────────────────────────  │
  │                                   │

§Alternative Transports

While D-Bus is the primary transport, adapters can implement other mechanisms:

  • Unix Socket: Direct socket communication
  • File Watching: QuickShell watches a file for changes
  • Signals: Unix signals for simple commands

§Example

ⓘ
use fernctl::ports::outbound::IpcPort;
use fernctl::adapters::DbusIpcAdapter;

let ipc = DbusIpcAdapter::new()?;

// Reload theme
ipc.reload_theme(&theme)?;

// Check if shell is running
if ipc.is_shell_running() {
    ipc.send_command("refresh")?;
}

§Error Handling

IPC operations can fail for various reasons:

ErrorCauseRecovery
Not runningQuickShell not startedStart the shell
TimeoutShell not respondingRestart the shell
Protocol errorVersion mismatchUpdate fernctl

Required Methods§

Source

fn reload_theme(&self, theme: &Theme) -> Result<()>

Signals QuickShell to reload its theme.

This sends the updated theme to QuickShell for live application. The shell will re-read the configuration and update all components.

§Arguments
  • theme — The new theme to apply
§Errors
  • [FernError::Ipc] if QuickShell is not running
  • [FernError::Ipc] if the reload times out
§Example
ⓘ
// Save theme to disk first
persist.save_theme(&theme, config_path)?;

// Then signal reload
ipc.reload_theme(&theme)?;
Source

fn send_command(&self, command: &str) -> Result<()>

Sends a raw command to QuickShell.

Commands are shell-specific strings that trigger actions.

§Built-in Commands
CommandEffect
refreshRefresh all modules
restartRestart the shell
quitGracefully exit
§Arguments
  • command — The command string to send
§Errors

Returns an error if the command cannot be sent or is rejected.

§Example
ⓘ
ipc.send_command("refresh")?;
Source

fn is_shell_running(&self) -> bool

Checks if QuickShell is currently running.

This performs a lightweight check (e.g., pinging the D-Bus service) to determine if the shell is available for commands.

§Returns

true if QuickShell is running and responding.

§Example
ⓘ
if !ipc.is_shell_running() {
    eprintln!("QuickShell is not running");
    return Ok(()); // Theme saved, will be applied on next start
}
Source

fn shell_version(&self) -> Option<String>

Returns the version of the running QuickShell instance.

Useful for compatibility checks and debugging.

§Returns

The version string, or None if the shell is not running or the version cannot be determined.

§Example
ⓘ
if let Some(version) = ipc.shell_version() {
    println!("QuickShell version: {}", version);
}
Source

fn ping(&self) -> Result<u64>

Pings the shell to check connectivity.

This is a more thorough check than [is_shell_running], verifying that the shell can receive and respond to messages.

§Returns

The round-trip time in milliseconds, or an error if the ping failed.

§Example
ⓘ
match ipc.ping() {
    Ok(ms) => println!("Shell responded in {}ms", ms),
    Err(e) => eprintln!("Shell not responding: {}", e),
}

Implementors§