Initial go port of epics

pkg/ca/doc.go

@@ -0,0 +1,65 @@
+// 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