receive

type AtomicTime struct {
	// contains filtered or unexported fields
}

type Config struct {
	InitialSequenceNumber  circular.Number
	PeriodicACKInterval    uint64 // microseconds
	PeriodicNAKInterval    uint64 // microseconds
	OnSendACK              func(seq circular.Number, light bool)
	OnSendNAK              func(list []circular.Number)
	OnDeliver              func(p packet.Packet)
	PacketReorderAlgorithm string                     // "list" (default) or "btree"
	BTreeDegree            int                        // B-tree degree (default: 32, only used if PacketReorderAlgorithm == "btree")
	LockTimingMetrics      *metrics.LockTimingMetrics // Optional lock timing metrics for performance monitoring
	ConnectionMetrics      *metrics.ConnectionMetrics // For atomic statistics updates

	// Buffer pool for zero-copy support (Phase 2: Lockless Design)
	// When provided, receiver.releasePacketFully() returns buffers to this pool
	BufferPool *sync.Pool

	// NAK btree configuration (Phase 4)
	UseNakBtree            bool    // Enable NAK btree for improved out-of-order handling
	SuppressImmediateNak   bool    // Suppress immediate NAK, let periodic NAK handle gaps
	TsbpdDelay             uint64  // Microseconds, for scan window calculation
	NakRecentPercent       float64 // Percentage of TSBPD delay for "recent" window (e.g., 0.10)
	NakMergeGap            uint32  // Maximum gap to merge into a single range
	NakConsolidationBudget uint64  // Microseconds, time budget for consolidation

	// FastNAK configuration
	FastNakEnabled       bool   // Enable FastNAK after silence
	FastNakThresholdUs   uint64 // Microseconds, silence threshold to trigger FastNAK
	FastNakRecentEnabled bool   // Enable FastNAKRecent to detect sequence jumps

	// NAK btree expiry configuration (nak_btree_expiry_optimization.md)
	NakExpiryMargin     float64 // Margin for expiry: threshold = now + RTO*(1+margin), default 0.10
	EWMAWarmupThreshold uint32  // Min samples before EWMA trusted (0=disabled), default 32

	// Light ACK configuration (Phase 5: ACK Optimization)
	LightACKDifference uint32 // Send Light ACK after N packets progress (default: 64)

	// Lock-free ring buffer configuration (Phase 3: Lockless Design)
	// When enabled, Push() writes to ring (lock-free), Tick() drains ring before processing
	UsePacketRing             bool          // Enable lock-free ring for packet handoff
	PacketRingSize            int           // Ring capacity per shard (must be power of 2)
	PacketRingShards          int           // Number of shards (must be power of 2)
	PacketRingMaxRetries      int           // Max immediate retries before backoff
	PacketRingBackoffDuration time.Duration // Delay between backoff retries
	PacketRingMaxBackoffs     int           // Max backoff iterations (0 = unlimited)
	PacketRingRetryStrategy   string        // Retry strategy: "", "sleep", "next", "random", "adaptive", "spin", "hybrid"

	// Event loop configuration (Phase 4: Lockless Design)
	// When enabled, replaces timer-driven Tick() with continuous event loop
	// REQUIRES: UsePacketRing=true (event loop consumes from ring)
	UseEventLoop          bool          // Enable continuous event loop
	EventLoopRateInterval time.Duration // Rate metric calculation interval (default: 1s)
	BackoffColdStartPkts  int           // Packets before adaptive backoff engages
	BackoffMinSleep       time.Duration // Minimum sleep during idle periods
	BackoffMaxSleep       time.Duration // Maximum sleep during idle periods

	// Time base configuration (Phase 10: EventLoop Time Fix)
	// When set, nowFn returns time relative to connection start, matching PktTsbpdTime.
	// This is REQUIRED for EventLoop mode to correctly handle TSBPD delivery.
	//
	// Without these fields: nowFn returns absolute Unix time (~1.7 trillion µs)
	// With these fields: nowFn returns TsbpdTimeBase + elapsed_since_StartTime
	//
	// PktTsbpdTime is calculated as: tsbpdTimeBase + timestamp + tsbpdDelay
	// For correct TSBPD comparison, nowFn must use the same time base.
	TsbpdTimeBase uint64    // Time base from connection (same as c.tsbpdTimeBase)
	StartTime     time.Time // Connection start time (same as c.start)

	// Debug logging (for investigation)
	// LogFunc is called for debug logging following the gosrt pattern:
	//   LogFunc("receiver:nak:debug", func() string { return "message" })
	Debug   bool                        // Enable debug logging
	LogFunc func(string, func() string) // Logging callback (lazy evaluation)

	// ProcessConnectionControlPackets is called by EventLoop to process
	// connection-level control packets (ACKACK, KEEPALIVE).
	// Returns number of packets processed.
	// Set by connection.go to c.drainRecvControlRing.
	// This allows control packets to be processed inline in EventLoop
	// rather than by a separate polling goroutine, eliminating latency.
	ProcessConnectionControlPackets func() int
}

type NAKEntry struct {
	Start uint32
	End   uint32 // Same as Start for singles
}

type NakEntryWithTime struct {
	Seq           uint32 // Missing sequence number
	TsbpdTimeUs   uint64 // TSBPD release time for this sequence (microseconds) - for expiry
	LastNakedAtUs uint64 // When we last sent NAK for this seq (microseconds) - for suppression
	NakCount      uint32 // Number of times NAK'd
}

type RecvControlPacket struct {
	// Type identifies the control packet type
	Type RecvControlPacketType

	// ACKNumber is the ACK number being acknowledged (for ACKACK only)
	ACKNumber uint32

	// Timestamp is the arrival time in nanoseconds (time.Now().UnixNano())
	// Captured at push time to ensure accurate RTT calculation
	Timestamp int64
}

type RecvControlPacketType uint8

type RecvControlRing struct {
	*common.ControlRing[RecvControlPacket]
}