From f5c38569d65b2cdf2624604df902b9cd33ee6ac5 Mon Sep 17 00:00:00 2001 From: Lorenzo Manacorda Date: Fri, 29 Sep 2017 17:14:13 +0200 Subject: [PATCH] Add or update some API docs Some functions were undocumented, some of them had wrong docs or typos, some of them needed a small update in docs after the reload-on-configuration-change work. Signed-off-by: Lorenzo Manacorda --- components/sup/src/manager/mod.rs | 1 + components/sup/src/manager/service/config.rs | 6 +++- components/sup/src/manager/service/hooks.rs | 2 ++ components/sup/src/manager/service/mod.rs | 32 +++++++++++++------ components/sup/src/manager/service_updater.rs | 3 ++ components/sup/src/templating/context.rs | 3 ++ 6 files changed, 36 insertions(+), 11 deletions(-) diff --git a/components/sup/src/manager/mod.rs b/components/sup/src/manager/mod.rs index 5ffe7df1998..f6b18f4df58 100644 --- a/components/sup/src/manager/mod.rs +++ b/components/sup/src/manager/mod.rs @@ -667,6 +667,7 @@ impl Manager { } } + // Creates a rumor for the specified service. fn gossip_latest_service_rumor(&self, service: &Service) { let mut incarnation = 1; { diff --git a/components/sup/src/manager/service/config.rs b/components/sup/src/manager/service/config.rs index c4aede06b5b..525edbca008 100644 --- a/components/sup/src/manager/service/config.rs +++ b/components/sup/src/manager/service/config.rs @@ -139,7 +139,7 @@ impl Cfg { /// Updates the service configuration with data from a census group if the census group has /// newer data than the current configuration. /// - /// Returns true if the configuration was updated. + /// Returns `true` if the configuration was updated. pub fn update(&mut self, census_group: &CensusGroup) -> bool { match census_group.service_config { Some(ref config) => { @@ -260,6 +260,7 @@ impl Cfg { Self::load_toml_file(path, USER_CONFIG_FILE) } + /// Reloads the user configuration file. pub fn reload_user(&mut self) -> Result<()> { let user = Self::load_user(&self.user_config_path)?; self.user = user; @@ -351,6 +352,7 @@ impl Serialize for Cfg { } #[derive(Debug)] +/// Renders configuration templates into config files. pub struct CfgRenderer(TemplateRenderer); impl CfgRenderer { @@ -388,6 +390,8 @@ impl CfgRenderer { } /// Compile and write all configuration files to the configuration directory. + /// + /// Returns `true` if the configuration has changed. pub fn compile(&self, pkg: &Pkg, ctx: &RenderContext) -> Result { // JW TODO: This function is loaded with IO errors that will be converted a Supervisor // error resulting in the end-user not knowing what the fuck happned at all. We need to go diff --git a/components/sup/src/manager/service/hooks.rs b/components/sup/src/manager/service/hooks.rs index af937bf5f56..8439629d035 100644 --- a/components/sup/src/manager/service/hooks.rs +++ b/components/sup/src/manager/service/hooks.rs @@ -98,6 +98,8 @@ pub trait Hook: fmt::Debug + Sized { fn new(service_group: &ServiceGroup, render_pair: RenderPair) -> Self; /// Compile a hook into its destination service directory. + /// + /// Returns `true` if the hook has changed. fn compile(&self, service_group: &ServiceGroup, ctx: &RenderContext) -> Result { let content = self.renderer().render(Self::file_name(), ctx)?; if write_hook(&content, self.path())? { diff --git a/components/sup/src/manager/service/mod.rs b/components/sup/src/manager/service/mod.rs index 78e4147808a..c7b36f408fe 100644 --- a/components/sup/src/manager/service/mod.rs +++ b/components/sup/src/manager/service/mod.rs @@ -263,6 +263,7 @@ impl Service { } } + /// Runs the reconfigure hook if present, otherwise restarts the service. fn reload(&mut self, launcher: &LauncherCli) { self.needs_reload = false; if self.process_down() || self.hooks.reload.is_none() { @@ -291,6 +292,9 @@ impl Service { self.supervisor.state_entered } + /// Performs updates and executes hooks. + /// + /// Returns `true` if the service was updated. pub fn tick(&mut self, census_ring: &CensusRing, launcher: &LauncherCli) -> bool { if !self.initialized { if !self.all_binds_satisfied(census_ring) { @@ -409,10 +413,10 @@ impl Service { self.supervisor.state == ProcessState::Down } - /// Compares the current state of the service to the current state of the census ring and - /// re-renders all templatable content to disk. + /// Compares the current state of the service to the current state of the census ring and the + /// user-config, and re-renders all templatable content to disk. /// - /// Returns true if any modifications were made. + /// Returns `true` if any modifications were made. fn update_templates(&mut self, census_ring: &CensusRing) -> bool { let census_group = census_ring.census_group_for(&self.service_group).expect( "Service update failed; unable to find own service group", @@ -452,7 +456,7 @@ impl Service { cfg_changed } - /// Replace the package of the running service and restart it's system process. + /// Replace the package of the running service and restart its system process. pub fn update_package(&mut self, package: PackageInstall, launcher: &LauncherCli) { match Pkg::from_install(package) { Ok(pkg) => { @@ -507,7 +511,7 @@ impl Service { rumor } - /// Run initialization hook if present + /// Run initialization hook if present. fn initialize(&mut self) { if self.initialized { return; @@ -523,8 +527,7 @@ impl Service { } } - /// Run reconfigure hook if present. Return false if it is not present, to trigger default - /// restart behavior. + /// Run reconfigure hook if present. fn reconfigure(&mut self) { self.needs_reconfiguration = false; if let Some(ref hook) = self.hooks.reconfigure { @@ -617,6 +620,8 @@ impl Service { } /// Helper for compiling configuration templates into configuration files. + /// + /// Returns `true` if the configuration has changed. fn compile_configuration(&self, ctx: &RenderContext) -> bool { match self.config_renderer.compile(&self.pkg, ctx) { Ok(true) => { @@ -636,6 +641,8 @@ impl Service { /// Helper for compiling hook templates into hooks. /// /// This function will also perform any necessary post-compilation tasks. + /// + /// Returns `true` if any hooks have changed. fn compile_hooks(&self, ctx: &RenderContext) -> bool { let changed = self.hooks.compile(&self.service_group, ctx); if let Some(err) = self.copy_run().err() { @@ -699,13 +706,14 @@ impl Service { if self.needs_reload || self.process_down() || self.needs_reconfiguration { self.reload(launcher); if self.needs_reconfiguration { + // NOTE this only runs the hook if it's defined self.reconfigure() } } } } - /// Run file_updated hook if present + /// Run file_updated hook if present. fn file_updated(&self) -> bool { if self.initialized { if let Some(ref hook) = self.hooks.file_updated { @@ -719,9 +727,11 @@ impl Service { false } - /// Write service files from gossip data to disk. + /// Write service files from gossip data to disk under + /// [`svc_files_path()`](../../fs/fn.svc_files_path.html). /// - /// Returns true if a file was changed, added, or removed, and false if there were no updates. + /// Returns `true` if a file was changed, added, or removed, and + /// `false` if there were no updates. fn update_service_files(&mut self, census_ring: &CensusRing) -> bool { let census_group = census_ring.census_group_for(&self.service_group).expect( "Service update service files failed; unable to find own service group", @@ -782,11 +792,13 @@ impl Service { self.cache_health_check(check_result); } + // Returns `false` if the write fails. fn cache_service_file(&mut self, service_file: &ServiceFile) -> bool { let file = self.pkg.svc_files_path.join(&service_file.filename); self.write_cache_file(file, &service_file.body) } + // Returns `false` if the write fails. fn write_cache_file(&self, file: T, contents: &[u8]) -> bool where T: AsRef, diff --git a/components/sup/src/manager/service_updater.rs b/components/sup/src/manager/service_updater.rs index 3d976c03f08..8ab2a9f7c4a 100644 --- a/components/sup/src/manager/service_updater.rs +++ b/components/sup/src/manager/service_updater.rs @@ -62,6 +62,9 @@ enum FollowerState { Updating(Receiver), } +/// The ServiceUpdater is in charge of updating a Service when a more recent version of a package +/// has been published to a depot or installed to the local package cache. +/// To use an update strategy, the supervisor must be configured to watch a depot for new versions. pub struct ServiceUpdater { states: UpdaterStateList, butterfly: butterfly::Server, diff --git a/components/sup/src/templating/context.rs b/components/sup/src/templating/context.rs index 64ec149e5d3..6e29dcdca37 100644 --- a/components/sup/src/templating/context.rs +++ b/components/sup/src/templating/context.rs @@ -53,6 +53,9 @@ impl<'a> BindGroup<'a> { } } +/// The context of a render call. +/// +/// It stores information on a Service and its configuration. #[derive(Clone, Debug, Serialize)] pub struct RenderContext<'a> { pub sys: &'a Sys,