// Package ca implements an EPICS Channel Access (CA) client in pure Go.
//
// It requires no CGo, no libca, and no EPICS installation on the build machine.
// A single [Client] manages connections to one or more IOCs, multiplexing
// channels over shared TCP virtual circuits that survive IOC restarts.
//
// # Quick start
//
//	// Configure from standard EPICS environment variables.
//	cli, err := ca.NewClient(ctx, ca.ConfigFromEnv())
//	if err != nil { ... }
//	defer cli.Close()
//
//	// Subscribe to live monitor updates.
//	ch := make(chan proto.TimeValue, 16)
//	cancel, err := cli.Subscribe(ctx, "MY:PV", ch)
//	if err != nil { ... }
//	defer cancel()
//	for tv := range ch {
//	    fmt.Println(tv.Timestamp, tv.Double)
//	}
//
//	// One-shot read (current value).
//	tv, err := cli.Get(ctx, "MY:PV")
//
//	// Retrieve full control-block metadata (units, display limits, enum strings).
//	ci, err := cli.GetCtrl(ctx, "MY:PV")
//	if ci.Double != nil {
//	    fmt.Println(ci.Double.Units, ci.Double.UpperDispLimit)
//	}
//
//	// Write a new value (fire-and-forget).
//	err = cli.Put(ctx, "MY:PV", 42.0)
//
// # Configuration
//
// [ConfigFromEnv] reads the standard EPICS CA environment variables:
//
//	EPICS_CA_ADDR_LIST        space-separated list of server addresses
//	EPICS_CA_AUTO_ADDR_LIST   set to "NO" to disable local broadcast
//
// Alternatively, construct [Config] directly and pass to [NewClient].
//
// # Protocol
//
// The library speaks Channel Access protocol version 4.13 over UDP (search,
// port 5064) and TCP (data, port 5064).  It does not use the CA Repeater;
// it sends search requests directly to the addresses in [Config.AddrList].
//
// UDP search uses exponential back-off (100 ms → 30 s) and retries until the
// PV is found or the context is cancelled.
//
// # Reconnection
//
// When an IOC restarts, the library detects the broken TCP connection and
// reconnects automatically.  All active subscriptions are re-established
// transparently after the new CREATE_CHAN handshake completes.
// Callers blocked in [Client.Get] or [Client.Put] during a reconnect will
// receive an error and should retry.
//
// # Thread safety
//
// All exported methods are safe for concurrent use from multiple goroutines.
// A single [Client] can be shared across the entire application.
package ca