Struct HostController 

pub struct HostController {
    pub data_dir: Arc<ServerDataDir>,
    pub page_pool: PagePool,
    /* private fields */
}

A host controller manages the lifecycle of spacetime databases and their associated modules.

This type is, and must remain, cheap to clone. All of its fields should either be Copy, enclosed in an Arc, or have some other fast Clone implementation.

Fields

data_dir: Arc<ServerDataDir>

The root directory for database data.

page_pool: PagePool

The page pool all databases will use by cloning the ref counted pool.

Implementations

impl HostController

pub fn new( data_dir: Arc<ServerDataDir>, default_config: Config, program_storage: ProgramStorage, energy_monitor: Arc<impl EnergyMonitor>, durability: Arc<dyn DurabilityProvider>, db_cores: JobCores, ) -> Self

pub fn set_program_storage(&mut self, ps: ProgramStorage)

Replace the ProgramStorage used by this controller.

pub async fn get_or_launch_module_host( &self, database: Database, replica_id: u64, ) -> Result<ModuleHost>

Get a ModuleHost managed by this controller, or launch it from persistent state.

If the host is not running, it is started according to the default db::Config set for this controller. The underlying database is restored from existing data at its canonical filesystem location iff the default config mandates disk storage.

The module will be instantiated from the program bytes stored in an existing database. If the database is empty, the program_bytes_address of the given Database will be used to load the program from the controller’s ProgramStorage. The initialization procedure (schema creation, __init__ reducer) will be invoked on the found module, and the database will be marked as initialized.

See also: Self::get_module_host

pub async fn watch_maybe_launch_module_host( &self, database: Database, replica_id: u64, ) -> Result<Receiver<ModuleHost>>

Like Self::get_or_launch_module_host, use a ModuleHost managed by this controller, or launch it if it is not running.

Instead of a ModuleHost, this returns a watch::Receiver which gets notified each time the module is updated.

See also: Self::watch_module_host

pub async fn check_module_validity( &self, database: Database, program: Program, ) -> Result<Arc<ModuleInfo>>

Construct an in-memory instance of database running program, initialize it, then immediately destroy it.

This is used during an initial, fresh publish operation in order to check the program’s validity as a module, since some validity checks we’d like to do (e.g. typechecking RLS filters) require a fully instantiated database.

This is not necessary during hotswap publishes, as the automigration planner and executor accomplish the same validity checks.

pub async fn using_database<F, T>( &self, database: Database, replica_id: u64, f: F, ) -> Result<T>

where F: FnOnce(&RelationalDB) -> T + Send + 'static, T: Send + 'static,

Run a computation on the RelationalDB of a ModuleHost managed by this controller, launching the host if necessary.

If the computation F panics, the host is removed from this controller, releasing its resources.

pub async fn update_module_host( &self, database: Database, host_type: HostType, replica_id: u64, program_bytes: Box<[u8]>, ) -> Result<UpdateDatabaseResult>

Update the ModuleHost identified by replica_id to the given program.

The host may not be running, in which case it is spawned (see Self::get_or_launch_module_host for details on what this entails).

If the host was running, and the update fails, the previous version of the host keeps running.

pub async fn init_maybe_update_module_host( &self, database: Database, replica_id: u64, expected_hash: Option<Hash>, ) -> Result<Receiver<ModuleHost>>

Start the host replica_id and conditionally update it.

If the host was not initialized before, it is initialized with the program Database::initial_program, which is loaded from the controller’s ProgramStorage.

If it was already initialized and its stored program hash matches Database::initial_program, no further action is taken.

Otherwise, if expected_hash is Some and does not match the stored hash, an error is returned.

Otherwise, the host is updated to Database::initial_program, loading the program data from the controller’s ProgramStorage.

Note that this ascribes different semantics to Database::initial_program than elsewhere, where the Database value is provided by the control database. The method is mainly useful for bootstrapping the control database itself.

pub async fn exit_module_host(&self, replica_id: u64) -> Result<(), Error>

Release all resources of the ModuleHost identified by replica_id, and deregister it from the controller.

pub async fn get_module_host( &self, replica_id: u64, ) -> Result<ModuleHost, NoSuchModule>

Get the ModuleHost identified by replica_id or return an error if it is not registered with the controller.

See Self::get_or_launch_module_host for a variant which launches the host if it is not running.

pub async fn watch_module_host( &self, replica_id: u64, ) -> Result<Receiver<ModuleHost>, NoSuchModule>

Subscribe to updates of the ModuleHost identified by replica_id, or return an error if it is not registered with the controller.

See Self::watch_maybe_launch_module_host for a variant which launches the host if it is not running.

pub async fn has_module_host(&self, replica_id: u64) -> bool

true if the module host replica_id is currently registered with the controller.

Trait Implementations

impl Clone for HostController

fn clone(&self) -> HostController

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.