group_summary.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

// PoolGroupSummary is a lightweight group inspection view.
//
// Summary is read-only, caller-owned, copy-safe state. It does not retain full
// reports, run coordinator ticks, tick partitions, publish policy or budgets,
// apply pressure, execute Pool trim, or start/stop/retime schedulers. Unlike
// Snapshot, Summary intentionally omits full partition snapshots and all nested
// Pool class/shard snapshots. It is observational across partitions and does
// not claim a distributed transaction.
type PoolGroupSummary 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

	// 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

	// PartitionCount is the number of group-owned partitions.
	PartitionCount int

	// PoolCount is the aggregate number of Pools across group-owned partitions.
	PoolCount int

	// PoolCounters contains aggregate retained-storage Pool counters.
	PoolCounters PoolCountersSnapshot

	// LeaseCounters contains aggregate ownership-layer counters.
	LeaseCounters LeaseCountersSnapshot

	// Metrics is an aggregate projection derived from the summary sample.
	Metrics PoolGroupMetrics

	// Partitions contains lightweight summaries for group-owned partitions.
	Partitions []PoolGroupPartitionSummary
}

// PoolGroupPartitionSummary is one named partition summary inside a group.
type PoolGroupPartitionSummary 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 summary
	// only observes this child state; it does not manage partition schedulers.
	Scheduler ControllerSchedulerSnapshot

	// PoolCount is the number of Pools represented by the partition summary.
	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

	// ActiveLeaseCount is the number of checked-out partition leases.
	ActiveLeaseCount int
}

// Summary returns a lightweight group inspection summary.
//
// Snapshot remains the full diagnostic tree. Summary uses PoolPartition.Summary
// for child state, so it does not materialize nested Pool, class, or shard DTOs.
func (g *PoolGroup) Summary() PoolGroupSummary {
	g.mustBeInitialized()

	runtime := g.currentRuntimeSnapshot()
	sample := PoolGroupSample{
		Generation:       g.generation.Load(),
		PolicyGeneration: runtime.Generation,
		Lifecycle:        g.lifecycle.Load(),
		PartitionCount:   g.registry.len(),
		Aggregate: PoolPartitionSample{
			Generation:       g.generation.Load(),
			PolicyGeneration: runtime.Generation,
			Lifecycle:        g.lifecycle.Load(),
			Scope:            PoolPartitionSampleScopePartition,
		},
	}

	partitions := make([]PoolGroupPartitionSummary, 0, g.registry.len())
	for _, entry := range g.registry.entries {
		partitionSummary := entry.partition.Summary()
		partitions = append(partitions, newPoolGroupPartitionSummary(entry.name, partitionSummary))
		addPartitionSummaryToGroupSample(&sample, partitionSummary)
	}
	sample.PoolCount = sample.Aggregate.PoolCount
	sample.CurrentRetainedBytes = sample.Aggregate.CurrentRetainedBytes
	sample.CurrentActiveBytes = sample.Aggregate.CurrentActiveBytes
	sample.CurrentOwnedBytes = sample.Aggregate.CurrentOwnedBytes

	pressure := PoolGroupPressureSnapshot(newEffectivePartitionPressureSnapshot(runtime.Policy.Pressure, runtime.Pressure, sample.Aggregate))
	return PoolGroupSummary{
		Name:              g.name,
		Lifecycle:         sample.Lifecycle,
		Generation:        sample.Generation,
		PolicyGeneration:  runtime.Generation,
		PressureSignal:    runtime.Pressure,
		Pressure:          pressure,
		Budget:            newGroupBudgetSnapshot(runtime.Policy.Budget, sample),
		CoordinatorStatus: g.ControllerStatus(),
		Scheduler:         g.coordinatorSchedulerSnapshot(runtime),
		PartitionCount:    sample.PartitionCount,
		PoolCount:         sample.PoolCount,
		PoolCounters:      sample.Aggregate.PoolCounters,
		LeaseCounters:     sample.Aggregate.LeaseCounters,
		Metrics:           newPoolGroupMetrics(g.name, sample),
		Partitions:        partitions,
	}
}

func newPoolGroupPartitionSummary(name string, summary PoolPartitionSummary) PoolGroupPartitionSummary {
	return PoolGroupPartitionSummary{
		Name:             name,
		Lifecycle:        summary.Lifecycle,
		Generation:       summary.Generation,
		PolicyGeneration: summary.PolicyGeneration,
		PressureSignal:   summary.PressureSignal,
		Pressure:         summary.Pressure,
		Budget:           summary.Budget,
		ControllerStatus: summary.ControllerStatus,
		Scheduler:        summary.Scheduler,
		PoolCount:        summary.PoolCount,
		ActivePoolCount:  summary.ActivePoolCount,
		DirtyPoolCount:   summary.DirtyPoolCount,
		ActiveLeaseCount: summary.ActiveLeaseCount,
	}
}

func addPartitionSummaryToGroupSample(sample *PoolGroupSample, summary PoolPartitionSummary) {
	if sample == nil {
		return
	}
	partitionSample := PoolPartitionSample{
		Generation:           summary.Generation,
		PolicyGeneration:     summary.PolicyGeneration,
		Lifecycle:            summary.Lifecycle,
		Scope:                PoolPartitionSampleScopePartition,
		TotalPoolCount:       summary.PoolCount,
		SampledPoolCount:     summary.PoolCount,
		PoolCount:            summary.PoolCount,
		PoolCounters:         summary.PoolCounters,
		LeaseCounters:        summary.LeaseCounters,
		ActiveLeases:         summary.ActiveLeaseCount,
		CurrentRetainedBytes: summary.Metrics.CurrentRetainedBytes,
		CurrentActiveBytes:   summary.Metrics.CurrentActiveBytes,
		CurrentOwnedBytes:    summary.Metrics.CurrentOwnedBytes,
	}
	addPartitionSampleToGroupAggregate(&sample.Aggregate, partitionSample)
}

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