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:
| Error | Cause | Recovery |
|---|---|---|
| Not running | QuickShell not started | Start the shell |
| Timeout | Shell not responding | Restart the shell |
| Protocol error | Version mismatch | Update fernctl |
Required Methods§
Sourcefn reload_theme(&self, theme: &Theme) -> Result<()>
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)?;Sourcefn send_command(&self, command: &str) -> Result<()>
fn send_command(&self, command: &str) -> Result<()>
Sends a raw command to QuickShell.
Commands are shell-specific strings that trigger actions.
§Built-in Commands
| Command | Effect |
|---|---|
refresh | Refresh all modules |
restart | Restart the shell |
quit | Gracefully 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")?;Sourcefn is_shell_running(&self) -> bool
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
}Sourcefn shell_version(&self) -> Option<String>
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);
}Sourcefn ping(&self) -> Result<u64>
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),
}