group_snapshot.go

/*
  Copyright 2026 The ARCORIS Authors

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
*/

package bufferpool

// PoolGroupSnapshot is a diagnostic group snapshot.
//
// The snapshot is caller-owned and copy-safe. It is read-only inspection state:
// it does not run coordinator ticks, tick partitions, publish policy or
// budgets, apply pressure, execute Pool trim, or start/stop/retime schedulers.
// Group-level consistency is observational across partition snapshots, not a
// distributed transaction.
type PoolGroupSnapshot struct {
	// Name is diagnostic group metadata.
	Name string

	// Lifecycle is the observed group lifecycle state.
	Lifecycle LifecycleState

	// Generation is the observed group state/event generation.
	Generation Generation

	// PolicyGeneration is the observed group runtime-policy generation.
	PolicyGeneration Generation

	// Config is a defensive copy of normalized construction config.
	Config PoolGroupConfig

	// Policy is the observed group runtime policy.
	Policy PoolGroupPolicy

	// PressureSignal is the immutable pressure signal currently published into
	// the group runtime snapshot.
	PressureSignal PressureSignal

	// Pressure is the effective pressure interpretation for aggregate group
	// state.
	Pressure PoolGroupPressureSnapshot

	// Budget is the aggregate group budget projection.
	Budget PoolGroupBudgetSnapshot

	// CoordinatorStatus is the retained lightweight outcome of the last group
	// coordinator cycle.
	CoordinatorStatus PoolGroupControllerStatus

	// Scheduler describes the group-local coordinator scheduler runtime.
	Scheduler ControllerSchedulerSnapshot

	// Partitions contains diagnostic snapshots for group-owned partitions.
	Partitions []PoolGroupPartitionSnapshot

	// Metrics is an aggregate projection derived from one group sample.
	Metrics PoolGroupMetrics
}

// PoolGroupPartitionSnapshot is one named partition diagnostic snapshot.
type PoolGroupPartitionSnapshot struct {
	// Name is the group-local partition name.
	Name string

	// Lifecycle is the observed partition lifecycle state.
	Lifecycle LifecycleState

	// Generation is the observed partition state/event generation.
	Generation Generation

	// PolicyGeneration is the observed partition runtime-policy generation.
	PolicyGeneration Generation

	// PressureSignal is the partition runtime pressure signal.
	PressureSignal PressureSignal

	// Pressure is the partition effective pressure projection.
	Pressure PartitionPressureSnapshot

	// Budget is the partition budget projection.
	Budget PartitionBudgetSnapshot

	// ControllerStatus is the partition retained controller status.
	ControllerStatus PoolPartitionControllerStatus

	// Scheduler describes the partition-local scheduler runtime. Group snapshot
	// only observes this child state; it does not manage partition schedulers.
	Scheduler ControllerSchedulerSnapshot

	// PoolCount is the number of Pools represented by the partition snapshot.
	PoolCount int

	// ActivePoolCount is the number of active Pool markers in the partition.
	ActivePoolCount int

	// DirtyPoolCount is the number of dirty Pool markers in the partition.
	DirtyPoolCount int

	// Partition is the partition diagnostic snapshot.
	Partition PoolPartitionSnapshot
}

// Snapshot returns a diagnostic group snapshot.
//
// The snapshot is observational across partitions, not a global transaction.
// Metrics are derived from one group sample, while partition snapshots may
// reflect nearby different instants under concurrent activity. Snapshot is not
// controller input; coordinator code should use Sample or SampleInto. Snapshot
// is diagnostic and remains available after group close.
func (g *PoolGroup) Snapshot() PoolGroupSnapshot {
	g.mustBeInitialized()
	runtime := g.currentRuntimeSnapshot()
	var sample PoolGroupSample
	g.sampleWithRuntimeAndGeneration(&sample, runtime, g.generation.Load())

	partitions := make([]PoolGroupPartitionSnapshot, 0, g.registry.len())
	for _, entry := range g.registry.entries {
		partitionSnapshot := entry.partition.Snapshot()
		partitions = append(partitions, newPoolGroupPartitionSnapshot(entry.name, partitionSnapshot))
	}

	pressure := PoolGroupPressureSnapshot(newEffectivePartitionPressureSnapshot(runtime.Policy.Pressure, runtime.Pressure, sample.Aggregate))
	return PoolGroupSnapshot{
		Name:              g.name,
		Lifecycle:         g.lifecycle.Load(),
		Generation:        sample.Generation,
		PolicyGeneration:  runtime.Generation,
		Config:            g.Config(),
		Policy:            runtime.Policy,
		PressureSignal:    runtime.Pressure,
		Pressure:          pressure,
		Budget:            newGroupBudgetSnapshot(runtime.Policy.Budget, sample),
		CoordinatorStatus: g.ControllerStatus(),
		Scheduler:         g.coordinatorSchedulerSnapshot(runtime),
		Partitions:        partitions,
		Metrics:           newPoolGroupMetrics(g.name, sample),
	}
}

func newPoolGroupPartitionSnapshot(name string, snapshot PoolPartitionSnapshot) PoolGroupPartitionSnapshot {
	return PoolGroupPartitionSnapshot{
		Name:             name,
		Lifecycle:        snapshot.Lifecycle,
		Generation:       snapshot.Generation,
		PolicyGeneration: snapshot.PolicyGeneration,
		PressureSignal:   snapshot.PressureSignal,
		Pressure:         snapshot.Pressure,
		Budget:           snapshot.Budget,
		ControllerStatus: snapshot.ControllerStatus,
		Scheduler:        snapshot.Scheduler,
		PoolCount:        snapshot.PoolCount(),
		ActivePoolCount:  snapshot.ActivePoolCount,
		DirtyPoolCount:   snapshot.DirtyPoolCount,
		Partition:        snapshot,
	}
}

// PartitionCount returns the number of partition snapshots.
func (s PoolGroupSnapshot) PartitionCount() int { return len(s.Partitions) }

// IsEmpty reports whether snapshot contains no owned memory and no observed activity.
func (s PoolGroupSnapshot) IsEmpty() bool { return s.Metrics.IsZero() }