From 652479cf62fc53a979a90712f0428095179f5a64 Mon Sep 17 00:00:00 2001 From: John Spray Date: Thu, 16 Jan 2025 15:38:34 +0000 Subject: [PATCH] pageserver: update doc comments referencing renamed types --- pageserver/src/config.rs | 10 ++-- pageserver/src/consumption_metrics/metrics.rs | 8 +-- pageserver/src/metrics.rs | 2 +- pageserver/src/tenant.rs | 58 +++++++++---------- pageserver/src/tenant/mgr.rs | 8 +-- .../src/tenant/remote_timeline_client.rs | 4 +- pageserver/src/tenant/secondary/scheduler.rs | 2 +- pageserver/src/tenant/timeline.rs | 12 ++-- pageserver/src/tenant/timeline/uninit.rs | 6 +- 9 files changed, 55 insertions(+), 55 deletions(-) diff --git a/pageserver/src/config.rs b/pageserver/src/config.rs index 1651db8500..469b9e1c9c 100644 --- a/pageserver/src/config.rs +++ b/pageserver/src/config.rs @@ -109,13 +109,13 @@ pub struct PageServerConf { /// A lower value implicitly deprioritizes loading such tenants, vs. other work in the system. pub concurrent_tenant_warmup: ConfigurableSemaphore, - /// Number of concurrent [`Tenant::gather_size_inputs`](crate::tenant::Tenant::gather_size_inputs) allowed. + /// Number of concurrent [`TenantShard::gather_size_inputs`](crate::tenant::TenantShard::gather_size_inputs) allowed. pub concurrent_tenant_size_logical_size_queries: ConfigurableSemaphore, - /// Limit of concurrent [`Tenant::gather_size_inputs`] issued by module `eviction_task`. + /// Limit of concurrent [`TenantShard::gather_size_inputs`] issued by module `eviction_task`. /// The number of permits is the same as `concurrent_tenant_size_logical_size_queries`. /// See the comment in `eviction_task` for details. /// - /// [`Tenant::gather_size_inputs`]: crate::tenant::Tenant::gather_size_inputs + /// [`TenantShard::gather_size_inputs`]: crate::tenant::TenantShard::gather_size_inputs pub eviction_task_immitated_concurrent_logical_size_queries: ConfigurableSemaphore, // How often to collect metrics and send them to the metrics endpoint. @@ -509,10 +509,10 @@ impl ConfigurableSemaphore { /// Initializse using a non-zero amount of permits. /// /// Require a non-zero initial permits, because using permits == 0 is a crude way to disable a - /// feature such as [`Tenant::gather_size_inputs`]. Otherwise any semaphore using future will + /// feature such as [`TenantShard::gather_size_inputs`]. Otherwise any semaphore using future will /// behave like [`futures::future::pending`], just waiting until new permits are added. /// - /// [`Tenant::gather_size_inputs`]: crate::tenant::Tenant::gather_size_inputs + /// [`TenantShard::gather_size_inputs`]: crate::tenant::TenantShard::gather_size_inputs pub fn new(initial_permits: NonZeroUsize) -> Self { ConfigurableSemaphore { initial_permits, diff --git a/pageserver/src/consumption_metrics/metrics.rs b/pageserver/src/consumption_metrics/metrics.rs index a156701eeb..22d75b4483 100644 --- a/pageserver/src/consumption_metrics/metrics.rs +++ b/pageserver/src/consumption_metrics/metrics.rs @@ -174,9 +174,9 @@ impl MetricsKey { .absolute_values() } - /// [`Tenant::remote_size`] + /// [`TenantShard::remote_size`] /// - /// [`Tenant::remote_size`]: crate::tenant::Tenant::remote_size + /// [`TenantShard::remote_size`]: crate::tenant::TenantShard::remote_size const fn remote_storage_size(tenant_id: TenantId) -> AbsoluteValueFactory { MetricsKey { tenant_id, @@ -198,9 +198,9 @@ impl MetricsKey { .absolute_values() } - /// [`Tenant::cached_synthetic_size`] as refreshed by [`calculate_synthetic_size_worker`]. + /// [`TenantShard::cached_synthetic_size`] as refreshed by [`calculate_synthetic_size_worker`]. /// - /// [`Tenant::cached_synthetic_size`]: crate::tenant::Tenant::cached_synthetic_size + /// [`TenantShard::cached_synthetic_size`]: crate::tenant::TenantShard::cached_synthetic_size /// [`calculate_synthetic_size_worker`]: super::calculate_synthetic_size_worker const fn synthetic_size(tenant_id: TenantId) -> AbsoluteValueFactory { MetricsKey { diff --git a/pageserver/src/metrics.rs b/pageserver/src/metrics.rs index 5b1cbbad63..9fc3f7e860 100644 --- a/pageserver/src/metrics.rs +++ b/pageserver/src/metrics.rs @@ -920,7 +920,7 @@ pub(crate) static TIMELINE_EPHEMERAL_BYTES: Lazy = Lazy::new(|| { .expect("Failed to register metric") }); -/// Metrics related to the lifecycle of a [`crate::tenant::Tenant`] object: things +/// Metrics related to the lifecycle of a [`crate::tenant::TenantShard`] object: things /// like how long it took to load. /// /// Note that these are process-global metrics, _not_ per-tenant metrics. Per-tenant diff --git a/pageserver/src/tenant.rs b/pageserver/src/tenant.rs index de6a917d87..6fb6e79221 100644 --- a/pageserver/src/tenant.rs +++ b/pageserver/src/tenant.rs @@ -193,7 +193,7 @@ pub struct TenantSharedResources { pub l0_flush_global_state: L0FlushGlobalState, } -/// A [`Tenant`] is really an _attached_ tenant. The configuration +/// A [`TenantShard`] is really an _attached_ tenant. The configuration /// for an attached tenant is a subset of the [`LocationConf`], represented /// in this struct. #[derive(Clone)] @@ -295,7 +295,7 @@ pub struct TenantShard { shard_identity: ShardIdentity, /// The remote storage generation, used to protect S3 objects from split-brain. - /// Does not change over the lifetime of the [`Tenant`] object. + /// Does not change over the lifetime of the [`TenantShard`] object. /// /// This duplicates the generation stored in LocationConf, but that structure is mutable: /// this copy enforces the invariant that generatio doesn't change during a Tenant's lifetime. @@ -334,7 +334,7 @@ pub struct TenantShard { // Access to global deletion queue for when this tenant wants to schedule a deletion deletion_queue_client: DeletionQueueClient, - /// Cached logical sizes updated updated on each [`Tenant::gather_size_inputs`]. + /// Cached logical sizes updated updated on each [`TenantShard::gather_size_inputs`]. cached_logical_sizes: tokio::sync::Mutex>, cached_synthetic_tenant_size: Arc, @@ -364,7 +364,7 @@ pub struct TenantShard { pub(crate) gate: Gate, /// Throttle applied at the top of [`Timeline::get`]. - /// All [`Tenant::timelines`] of a given [`Tenant`] instance share the same [`throttle::Throttle`] instance. + /// All [`TenantShard::timelines`] of a given [`TenantShard`] instance share the same [`throttle::Throttle`] instance. pub(crate) pagestream_throttle: Arc, pub(crate) pagestream_throttle_metrics: Arc, @@ -860,7 +860,7 @@ impl Debug for SetStoppingError { } } -/// Arguments to [`Tenant::create_timeline`]. +/// Arguments to [`TenantShard::create_timeline`]. /// /// Not usable as an idempotency key for timeline creation because if [`CreateTimelineParamsBranch::ancestor_start_lsn`] /// is `None`, the result of the timeline create call is not deterministic. @@ -895,7 +895,7 @@ pub(crate) struct CreateTimelineParamsImportPgdata { pub(crate) idempotency_key: import_pgdata::index_part_format::IdempotencyKey, } -/// What is used to determine idempotency of a [`Tenant::create_timeline`] call in [`Tenant::start_creating_timeline`] in [`Tenant::start_creating_timeline`]. +/// What is used to determine idempotency of a [`TenantShard::create_timeline`] call in [`TenantShard::start_creating_timeline`] in [`TenantShard::start_creating_timeline`]. /// /// Each [`Timeline`] object holds [`Self`] as an immutable property in [`Timeline::create_idempotency`]. /// @@ -933,7 +933,7 @@ pub(crate) struct CreatingTimelineIdempotencyImportPgdata { idempotency_key: import_pgdata::index_part_format::IdempotencyKey, } -/// What is returned by [`Tenant::start_creating_timeline`]. +/// What is returned by [`TenantShard::start_creating_timeline`]. #[must_use] enum StartCreatingTimelineResult { CreateGuard(TimelineCreateGuard), @@ -961,13 +961,13 @@ struct TimelineInitAndSyncNeedsSpawnImportPgdata { guard: TimelineCreateGuard, } -/// What is returned by [`Tenant::create_timeline`]. +/// What is returned by [`TenantShard::create_timeline`]. enum CreateTimelineResult { Created(Arc), Idempotent(Arc), - /// IMPORTANT: This [`Arc`] object is not in [`Tenant::timelines`] when + /// IMPORTANT: This [`Arc`] object is not in [`TenantShard::timelines`] when /// we return this result, nor will this concrete object ever be added there. - /// Cf method comment on [`Tenant::create_timeline_import_pgdata`]. + /// Cf method comment on [`TenantShard::create_timeline_import_pgdata`]. ImportSpawned(Arc), } @@ -1336,7 +1336,7 @@ impl TenantShard { } } - // Ideally we should use Tenant::set_broken_no_wait, but it is not supposed to be used when tenant is in loading state. + // Ideally we should use TenantShard::set_broken_no_wait, but it is not supposed to be used when tenant is in loading state. enum BrokenVerbosity { Error, Info @@ -1704,7 +1704,7 @@ impl TenantShard { match effect { TimelineInitAndSyncResult::ReadyToActivate(_) => { - // activation happens later, on Tenant::activate + // activation happens later, on TenantShard::activate } TimelineInitAndSyncResult::NeedsSpawnImportPgdata( TimelineInitAndSyncNeedsSpawnImportPgdata { @@ -2333,14 +2333,14 @@ impl TenantShard { /// This is used by tests & import-from-basebackup. /// /// The returned [`UninitializedTimeline`] contains no data nor metadata and it is in - /// a state that will fail [`Tenant::load_remote_timeline`] because `disk_consistent_lsn=Lsn(0)`. + /// a state that will fail [`TenantShard::load_remote_timeline`] because `disk_consistent_lsn=Lsn(0)`. /// /// The caller is responsible for getting the timeline into a state that will be accepted - /// by [`Tenant::load_remote_timeline`] / [`Tenant::attach`]. + /// by [`TenantShard::load_remote_timeline`] / [`TenantShard::attach`]. /// Then they may call [`UninitializedTimeline::finish_creation`] to add the timeline - /// to the [`Tenant::timelines`]. + /// to the [`TenantShard::timelines`]. /// - /// Tests should use `Tenant::create_test_timeline` to set up the minimum required metadata keys. + /// Tests should use `TenantShard::create_test_timeline` to set up the minimum required metadata keys. pub(crate) async fn create_empty_timeline( self: &Arc, new_timeline_id: TimelineId, @@ -2635,9 +2635,9 @@ impl TenantShard { Ok(activated_timeline) } - /// The returned [`Arc`] is NOT in the [`Tenant::timelines`] map until the import + /// The returned [`Arc`] is NOT in the [`TenantShard::timelines`] map until the import /// completes in the background. A DIFFERENT [`Arc`] will be inserted into the - /// [`Tenant::timelines`] map when the import completes. + /// [`TenantShard::timelines`] map when the import completes. /// We only return an [`Arc`] here so the API handler can create a [`pageserver_api::models::TimelineInfo`] /// for the response. async fn create_timeline_import_pgdata( @@ -2780,10 +2780,10 @@ impl TenantShard { // Reload timeline from remote. // This proves that the remote state is attachable, and it reuses the code. // - // TODO: think about whether this is safe to do with concurrent Tenant::shutdown. + // TODO: think about whether this is safe to do with concurrent TenantShard::shutdown. // timeline_create_guard hols the tenant gate open, so, shutdown cannot _complete_ until we exit. - // But our activate() call might launch new background tasks after Tenant::shutdown - // already went past shutting down the Tenant::timelines, which this timeline here is no part of. + // But our activate() call might launch new background tasks after TenantShard::shutdown + // already went past shutting down the TenantShard::timelines, which this timeline here is no part of. // I think the same problem exists with the bootstrap & branch mgmt API tasks (tenant shutting // down while bootstrapping/branching + activating), but, the race condition is much more likely // to manifest because of the long runtime of this import task. @@ -2798,7 +2798,7 @@ impl TenantShard { // }; let timeline_id = timeline.timeline_id; - // load from object storage like Tenant::attach does + // load from object storage like TenantShard::attach does let resources = self.build_timeline_resources(timeline_id); let index_part = resources .remote_client @@ -3268,7 +3268,7 @@ impl TenantShard { } Err(SetStoppingError::AlreadyStopping(other)) => { // give caller the option to wait for this this shutdown - info!("Tenant::shutdown: AlreadyStopping"); + info!("TenantShard::shutdown: AlreadyStopping"); return Err(other); } }; @@ -3882,7 +3882,7 @@ impl TenantShard { update: F, ) -> anyhow::Result { // Use read-copy-update in order to avoid overwriting the location config - // state if this races with [`Tenant::set_new_location_config`]. Note that + // state if this races with [`TenantShard::set_new_location_config`]. Note that // this race is not possible if both request types come from the storage // controller (as they should!) because an exclusive op lock is required // on the storage controller side. @@ -3994,7 +3994,7 @@ impl TenantShard { Ok(timeline) } - /// [`Tenant::shutdown`] must be called before dropping the returned [`Tenant`] object + /// [`TenantShard::shutdown`] must be called before dropping the returned [`TenantShard`] object /// to ensure proper cleanup of background tasks and metrics. // // Allow too_many_arguments because a constructor's argument list naturally grows with the @@ -4243,11 +4243,11 @@ impl TenantShard { // Perform GC for each timeline. // - // Note that we don't hold the `Tenant::gc_cs` lock here because we don't want to delay the + // Note that we don't hold the `TenantShard::gc_cs` lock here because we don't want to delay the // branch creation task, which requires the GC lock. A GC iteration can run concurrently // with branch creation. // - // See comments in [`Tenant::branch_timeline`] for more information about why branch + // See comments in [`TenantShard::branch_timeline`] for more information about why branch // creation task can run concurrently with timeline's GC iteration. for timeline in gc_timelines { if cancel.is_cancelled() { @@ -4277,7 +4277,7 @@ impl TenantShard { /// Refreshes the Timeline::gc_info for all timelines, returning the /// vector of timelines which have [`Timeline::get_last_record_lsn`] past - /// [`Tenant::get_gc_horizon`]. + /// [`TenantShard::get_gc_horizon`]. /// /// This is usually executed as part of periodic gc, but can now be triggered more often. pub(crate) async fn refresh_gc_info( @@ -7285,7 +7285,7 @@ mod tests { let tline = tenant .create_empty_timeline(TIMELINE_ID, Lsn(0), DEFAULT_PG_VERSION, &ctx) .await?; - // Leave the timeline ID in [`Tenant::timelines_creating`] to exclude attempting to create it again + // Leave the timeline ID in [`TenantShard::timelines_creating`] to exclude attempting to create it again let raw_tline = tline.raw_timeline().unwrap(); raw_tline .shutdown(super::timeline::ShutdownMode::Hard) diff --git a/pageserver/src/tenant/mgr.rs b/pageserver/src/tenant/mgr.rs index d0433bc797..caa144abf1 100644 --- a/pageserver/src/tenant/mgr.rs +++ b/pageserver/src/tenant/mgr.rs @@ -107,7 +107,7 @@ pub(crate) enum TenantShardMap { /// [`init_tenant_mgr`] is done, all on-disk tenants have been loaded. /// New tenants can be added using [`tenant_map_acquire_slot`]. Open(BTreeMap), - /// The pageserver has entered shutdown mode via [`TenantManager::shutdown`]. + /// The pageserver has entered shutdown mode via [`TenantShardManager::shutdown`]. /// Existing tenants are still accessible, but no new tenants can be created. ShuttingDown(BTreeMap), } @@ -685,7 +685,7 @@ pub async fn init_tenant_mgr( }) } -/// Wrapper for Tenant::spawn that checks invariants before running +/// Wrapper for TenantShard::spawn that checks invariants before running #[allow(clippy::too_many_arguments)] fn tenant_spawn( conf: &'static PageServerConf, @@ -884,7 +884,7 @@ impl TenantShardManager { /// undergoing a state change (i.e. slot is InProgress). /// /// The return Tenant is not guaranteed to be active: check its status after obtaing it, or - /// use [`Tenant::wait_to_become_active`] before using it if you will do I/O on it. + /// use [`TenantShard::wait_to_become_active`] before using it if you will do I/O on it. pub(crate) fn get_attached_tenant_shard( &self, tenant_shard_id: TenantShardId, @@ -1530,7 +1530,7 @@ impl TenantShardManager { // Phase 1: Write out child shards' remote index files, in the parent tenant's current generation if let Err(e) = tenant.split_prepare(&child_shards).await { - // If [`Tenant::split_prepare`] fails, we must reload the tenant, because it might + // If [`TenantShard::split_prepare`] fails, we must reload the tenant, because it might // have been left in a partially-shut-down state. tracing::warn!("Failed to prepare for split: {e}, reloading Tenant before returning"); return Err(e); diff --git a/pageserver/src/tenant/remote_timeline_client.rs b/pageserver/src/tenant/remote_timeline_client.rs index 9fae6ca5a7..e15d7ea526 100644 --- a/pageserver/src/tenant/remote_timeline_client.rs +++ b/pageserver/src/tenant/remote_timeline_client.rs @@ -133,7 +133,7 @@ //! - Initiate upload queue with that [`IndexPart`]. //! - Reschedule all lost operations by comparing the local filesystem state //! and remote state as per [`IndexPart`]. This is done in -//! [`Tenant::timeline_init_and_sync`]. +//! [`TenantShard::timeline_init_and_sync`]. //! //! Note that if we crash during file deletion between the index update //! that removes the file from the list of files, and deleting the remote file, @@ -171,7 +171,7 @@ //! If no remote storage configuration is provided, the [`RemoteTimelineClient`] is //! not created and the uploads are skipped. //! -//! [`Tenant::timeline_init_and_sync`]: super::Tenant::timeline_init_and_sync +//! [`TenantShard::timeline_init_and_sync`]: super::TenantShard::timeline_init_and_sync //! [`Timeline::load_layer_map`]: super::Timeline::load_layer_map pub(crate) mod download; diff --git a/pageserver/src/tenant/secondary/scheduler.rs b/pageserver/src/tenant/secondary/scheduler.rs index e963c722b9..5466caffa9 100644 --- a/pageserver/src/tenant/secondary/scheduler.rs +++ b/pageserver/src/tenant/secondary/scheduler.rs @@ -361,7 +361,7 @@ where /// Periodic execution phase: inspect all attached tenants and schedule any work they require. /// - /// The type in `tenants` should be a tenant-like structure, e.g. [`crate::tenant::Tenant`] or [`crate::tenant::secondary::SecondaryTenant`] + /// The type in `tenants` should be a tenant-like structure, e.g. [`crate::tenant::TenantShard`] or [`crate::tenant::secondary::SecondaryTenant`] /// /// This function resets the pending list: it is assumed that the caller may change their mind about /// which tenants need work between calls to schedule_iteration. diff --git a/pageserver/src/tenant/timeline.rs b/pageserver/src/tenant/timeline.rs index b44afd1ed7..fc44fccc95 100644 --- a/pageserver/src/tenant/timeline.rs +++ b/pageserver/src/tenant/timeline.rs @@ -413,7 +413,7 @@ pub struct Timeline { /// Timeline deletion will acquire both compaction and gc locks in whatever order. gc_lock: tokio::sync::Mutex<()>, - /// Cloned from [`super::Tenant::pagestream_throttle`] on construction. + /// Cloned from [`super::TenantShard::pagestream_throttle`] on construction. pub(crate) pagestream_throttle: Arc, /// Size estimator for aux file v2 @@ -2675,7 +2675,7 @@ impl Timeline { // (1) and (4) // TODO: this is basically a no-op now, should we remove it? self.remote_client.schedule_barrier()?; - // Tenant::create_timeline will wait for these uploads to happen before returning, or + // TenantShard::create_timeline will wait for these uploads to happen before returning, or // on retry. // Now that we have the full layer map, we may calculate the visibility of layers within it (a global scan) @@ -5634,8 +5634,8 @@ impl Timeline { /// Force create an image layer and place it into the layer map. /// - /// DO NOT use this function directly. Use [`Tenant::branch_timeline_test_with_layers`] - /// or [`Tenant::create_test_timeline_with_layers`] to ensure all these layers are + /// DO NOT use this function directly. Use [`TenantShard::branch_timeline_test_with_layers`] + /// or [`TenantShard::create_test_timeline_with_layers`] to ensure all these layers are /// placed into the layer map in one run AND be validated. #[cfg(test)] pub(super) async fn force_create_image_layer( @@ -5681,8 +5681,8 @@ impl Timeline { /// Force create a delta layer and place it into the layer map. /// - /// DO NOT use this function directly. Use [`Tenant::branch_timeline_test_with_layers`] - /// or [`Tenant::create_test_timeline_with_layers`] to ensure all these layers are + /// DO NOT use this function directly. Use [`TenantShard::branch_timeline_test_with_layers`] + /// or [`TenantShard::create_test_timeline_with_layers`] to ensure all these layers are /// placed into the layer map in one run AND be validated. #[cfg(test)] pub(super) async fn force_create_delta_layer( diff --git a/pageserver/src/tenant/timeline/uninit.rs b/pageserver/src/tenant/timeline/uninit.rs index fe1aee85d5..1019745579 100644 --- a/pageserver/src/tenant/timeline/uninit.rs +++ b/pageserver/src/tenant/timeline/uninit.rs @@ -16,7 +16,7 @@ use super::Timeline; /// A timeline with some of its files on disk, being initialized. /// This struct ensures the atomicity of the timeline init: it's either properly created and inserted into pageserver's memory, or /// its local files are removed. If we crash while this class exists, then the timeline's local -/// state is cleaned up during [`Tenant::clean_up_timelines`], because the timeline's content isn't in remote storage. +/// state is cleaned up during [`TenantShard::clean_up_timelines`], because the timeline's content isn't in remote storage. /// /// The caller is responsible for proper timeline data filling before the final init. #[must_use] @@ -163,13 +163,13 @@ pub(crate) fn cleanup_timeline_directory(create_guard: TimelineCreateGuard) { error!("Failed to clean up uninitialized timeline directory {timeline_path:?}: {e:?}") } } - // Having cleaned up, we can release this TimelineId in `[Tenant::timelines_creating]` to allow other + // Having cleaned up, we can release this TimelineId in `[TenantShard::timelines_creating]` to allow other // timeline creation attempts under this TimelineId to proceed drop(create_guard); } /// A guard for timeline creations in process: as long as this object exists, the timeline ID -/// is kept in `[Tenant::timelines_creating]` to exclude concurrent attempts to create the same timeline. +/// is kept in `[TenantShard::timelines_creating]` to exclude concurrent attempts to create the same timeline. #[must_use] pub(crate) struct TimelineCreateGuard { pub(crate) _tenant_gate_guard: GateGuard,