You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by sr...@apache.org on 2026/07/06 18:53:53 UTC
(plc4x) 08/09: feat(plc4go): shared serial ports and inter-frame write pacing
This is an automated email from the ASF dual-hosted git repository.
sruehl pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git
commit b5259d7916f6bec449613ea18225f876d2ed0f62
Author: Sebastian Rühl <sr...@apache.org>
AuthorDate: Mon Jul 6 16:24:59 2026 +0200
feat(plc4go): shared serial ports and inter-frame write pacing
New serial options: "reuse-port" shares one physical port between
multiple connections (multi-slave Modbus RTU) — broadcast reads into
per-subscriber bounded drop-oldest buffers, serialized writes, a
refcounted per-transport registry with hard errors on config mismatch —
and "interframe-delay" enforces minimum write silence measured from the
later of last-write-end and last-received-byte, on shared and dedicated
ports alike. Subscriptions implement the serialport.Port interface, so
the deadline/buffering/codec layers are unchanged.
---
RELEASE_NOTES | 4 +
plc4go/spi/transports/serial/Transport.go | 5 +-
plc4go/spi/transports/serial/TransportInstance.go | 63 ++--
.../serial/TransportInstance_pty_test.go | 71 +++++
.../transports/serial/TransportInstance_test.go | 17 ++
plc4go/spi/transports/serial/Transport_test.go | 3 +-
plc4go/spi/transports/serial/deadline_reader.go | 11 +-
.../spi/transports/serial/deadline_reader_test.go | 10 +-
plc4go/spi/transports/serial/options.go | 21 ++
plc4go/spi/transports/serial/options_test.go | 28 ++
plc4go/spi/transports/serial/pacer.go | 77 +++++
plc4go/spi/transports/serial/pacer_test.go | 80 +++++
plc4go/spi/transports/serial/ring_buffer.go | 173 +++++++++++
plc4go/spi/transports/serial/ring_buffer_test.go | 122 ++++++++
plc4go/spi/transports/serial/shared_port.go | 337 +++++++++++++++++++++
.../spi/transports/serial/shared_port_pty_test.go | 175 +++++++++++
16 files changed, 1168 insertions(+), 29 deletions(-)
diff --git a/RELEASE_NOTES b/RELEASE_NOTES
index dffd8b8e0e..9d76d24faf 100644
--- a/RELEASE_NOTES
+++ b/RELEASE_NOTES
@@ -19,6 +19,10 @@ New Features
- The Go serial transport now supports the full set of serial
options in the connection string: data-bits, stop-bits, parity,
flow-control, dtr, rts, read-timeout and write-timeout.
+- The Go serial transport supports sharing one physical serial port
+ between multiple connections ("reuse-port", e.g. multi-slave Modbus
+ RTU) with broadcast reads and serialized writes, plus inter-frame
+ write pacing ("interframe-delay") on both shared and dedicated ports.
Incompatible changes
--------------------
diff --git a/plc4go/spi/transports/serial/Transport.go b/plc4go/spi/transports/serial/Transport.go
index 700e4ee04b..7cc828b1c3 100644
--- a/plc4go/spi/transports/serial/Transport.go
+++ b/plc4go/spi/transports/serial/Transport.go
@@ -31,13 +31,16 @@ import (
)
type Transport struct {
+ registry *sharedPortRegistry
+
log zerolog.Logger
}
func NewTransport(_options ...options.WithOption) *Transport {
customLogger := options.ExtractCustomLoggerOrDefaultToGlobal(_options...)
return &Transport{
- log: customLogger,
+ registry: newSharedPortRegistry(customLogger),
+ log: customLogger,
}
}
diff --git a/plc4go/spi/transports/serial/TransportInstance.go b/plc4go/spi/transports/serial/TransportInstance.go
index 562fc43b0a..f99fc91284 100644
--- a/plc4go/spi/transports/serial/TransportInstance.go
+++ b/plc4go/spi/transports/serial/TransportInstance.go
@@ -53,6 +53,7 @@ type TransportInstance struct {
transport *Transport
serialPort serialport.Port
armer *deadlineReader
+ pacer *pacer
reader *bufio.Reader
log zerolog.Logger
@@ -89,13 +90,35 @@ func (m *TransportInstance) Connect(ctx context.Context) error {
return errors.New("Already connected")
}
- serialPort, err := serialport.Open(m.SerialPortName, m.cfg.port)
- if err != nil {
- return errors.Wrap(err, "error connecting to serial port")
+ var serialPort serialport.Port
+ var err error
+ if m.cfg.reusePort {
+ if m.transport == nil {
+ return errors.New("reuse-port requires a transport-managed instance")
+ }
+ serialPort, err = m.transport.registry.acquire(m.SerialPortName, sharedPortConfig{
+ port: m.cfg.port,
+ dtr: m.cfg.dtr,
+ rts: m.cfg.rts,
+ interframeDelay: m.cfg.interframeDelay,
+ })
+ if err != nil {
+ return errors.Wrap(err, "error acquiring shared serial port")
+ }
+ m.serialPort = serialPort
+ // dtr/rts are applied by the registry at open; pacing lives inside
+ // the shared port's write path.
+ m.pacer = nil
+ } else {
+ serialPort, err = serialport.Open(m.SerialPortName, m.cfg.port)
+ if err != nil {
+ return errors.Wrap(err, "error connecting to serial port")
+ }
+ m.serialPort = serialPort
+ m.applyModemLines(serialPort)
+ m.pacer = newPacer(m.cfg.interframeDelay)
}
- m.serialPort = serialPort
- m.applyModemLines(serialPort)
- m.armer = newDeadlineReader(serialPort, m.cfg.readTimeout)
+ m.armer = newDeadlineReader(m.serialPort, m.cfg.readTimeout, m.pacer)
m.reader = bufio.NewReader(m.armer)
m.connected.Store(true)
return nil
@@ -134,13 +157,13 @@ func (m *TransportInstance) Close() error {
return nil
}
err := m.serialPort.Close()
- if err != nil {
- return errors.Wrap(err, "error closing serial port")
- }
m.serialPort = nil
m.armer = nil
-
+ m.pacer = nil
m.connected.Store(false)
+ if err != nil {
+ return errors.Wrap(err, "error closing serial port")
+ }
return nil
}
@@ -155,18 +178,20 @@ func (m *TransportInstance) Write(ctx context.Context, data []byte) error {
if m.serialPort == nil {
return errors.New("error writing to transport. No writer available")
}
- if deadline, ok := ctx.Deadline(); ok {
- if err := m.serialPort.SetWriteDeadline(deadline); err != nil {
- return errors.Wrap(err, "error setting write deadline")
- }
+ var deadline time.Time
+ if ctxDeadline, ok := ctx.Deadline(); ok {
+ deadline = ctxDeadline
} else if m.cfg.writeTimeout > 0 {
- if err := m.serialPort.SetWriteDeadline(time.Now().Add(m.cfg.writeTimeout)); err != nil {
- return errors.Wrap(err, "error setting write deadline")
- }
- } else if err := m.serialPort.SetWriteDeadline(time.Time{}); err != nil {
- return errors.Wrap(err, "error clearing write deadline")
+ deadline = time.Now().Add(m.cfg.writeTimeout)
+ }
+ if err := m.pacer.waitTurn(deadline); err != nil {
+ return errors.Wrap(err, "error pacing write")
+ }
+ if err := m.serialPort.SetWriteDeadline(deadline); err != nil {
+ return errors.Wrap(err, "error setting write deadline")
}
num, err := m.serialPort.Write(data)
+ m.pacer.noteActivity()
if err != nil {
return errors.Wrap(err, "error writing")
}
diff --git a/plc4go/spi/transports/serial/TransportInstance_pty_test.go b/plc4go/spi/transports/serial/TransportInstance_pty_test.go
index d5a94bae8b..a601d13f14 100644
--- a/plc4go/spi/transports/serial/TransportInstance_pty_test.go
+++ b/plc4go/spi/transports/serial/TransportInstance_pty_test.go
@@ -32,6 +32,8 @@ import (
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"golang.org/x/sys/unix"
+
+ "github.com/apache/plc4x/plc4go/spi/transports"
)
// openPTY allocates a pseudo-terminal pair; the slave path stands in for a
@@ -173,3 +175,72 @@ func TestTransportInstance_ExplicitCtxDeadlineBeatsFallback(t *testing.T) {
require.Error(t, err)
assert.Less(t, elapsed, 5*time.Second, "the 100ms ctx deadline must win over the 60s fallback")
}
+
+func TestTransportInstance_ReusePortSharesOnePTY(t *testing.T) {
+ master, slavePath := openPTY(t)
+ transport := NewTransport()
+ options := map[string][]string{"reuse-port": {"true"}}
+
+ first, err := transport.CreateTransportInstance(url.URL{Scheme: "serial", Path: slavePath}, options)
+ require.NoError(t, err)
+ second, err := transport.CreateTransportInstance(url.URL{Scheme: "serial", Path: slavePath}, options)
+ require.NoError(t, err)
+
+ require.NoError(t, first.Connect(context.Background()))
+ t.Cleanup(func() { _ = first.Close() })
+ require.NoError(t, second.Connect(context.Background()))
+ t.Cleanup(func() { _ = second.Close() })
+
+ _, err = master.Write([]byte{0xCA, 0xFE})
+ require.NoError(t, err)
+
+ for _, instance := range []transports.TransportInstance{first, second} {
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ data, err := instance.Read(ctx, 2)
+ cancel()
+ require.NoError(t, err)
+ assert.Equal(t, []byte{0xCA, 0xFE}, data, "both connections see the broadcast")
+ }
+}
+
+func TestTransportInstance_ReusePortConfigMismatch(t *testing.T) {
+ _, slavePath := openPTY(t)
+ transport := NewTransport()
+
+ first, err := transport.CreateTransportInstance(url.URL{Scheme: "serial", Path: slavePath},
+ map[string][]string{"reuse-port": {"true"}, "baud-rate": {"9600"}})
+ require.NoError(t, err)
+ require.NoError(t, first.Connect(context.Background()))
+ t.Cleanup(func() { _ = first.Close() })
+
+ second, err := transport.CreateTransportInstance(url.URL{Scheme: "serial", Path: slavePath},
+ map[string][]string{"reuse-port": {"true"}, "baud-rate": {"19200"}})
+ require.NoError(t, err)
+ err = second.Connect(context.Background())
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), slavePath)
+}
+
+func TestTransportInstance_DedicatedInterframeDelayOnPTY(t *testing.T) {
+ master, slavePath := openPTY(t)
+ transport := NewTransport()
+ instance, err := transport.CreateTransportInstance(url.URL{Scheme: "serial", Path: slavePath},
+ map[string][]string{"interframe-delay": {"60"}})
+ require.NoError(t, err)
+ require.NoError(t, instance.Connect(context.Background()))
+ t.Cleanup(func() { _ = instance.Close() })
+
+ require.NoError(t, instance.Write(context.Background(), []byte{0x01}))
+ start := time.Now()
+ require.NoError(t, instance.Write(context.Background(), []byte{0x02}))
+ assert.GreaterOrEqual(t, time.Since(start), 50*time.Millisecond)
+
+ buf := make([]byte, 2)
+ total := 0
+ for total < 2 {
+ n, err := master.Read(buf[total:])
+ require.NoError(t, err)
+ total += n
+ }
+ assert.Equal(t, []byte{0x01, 0x02}, buf)
+}
diff --git a/plc4go/spi/transports/serial/TransportInstance_test.go b/plc4go/spi/transports/serial/TransportInstance_test.go
index 33e93cd013..808da7105e 100644
--- a/plc4go/spi/transports/serial/TransportInstance_test.go
+++ b/plc4go/spi/transports/serial/TransportInstance_test.go
@@ -371,3 +371,20 @@ func TestWrite_ZeroWriteTimeoutClearsDeadline(t *testing.T) {
require.Len(t, port.writeDeadlines, 1)
assert.True(t, port.writeDeadlines[0].IsZero())
}
+
+func TestWrite_DedicatedInterframePacing(t *testing.T) {
+ port := &recordingWritePort{}
+ m := NewTransportInstanceWithConfig("test", func() serialConfig {
+ c := defaultSerialConfig()
+ c.interframeDelay = 50 * time.Millisecond
+ return c
+ }(), NewTransport())
+ m.serialPort = port
+ m.pacer = newPacer(m.cfg.interframeDelay)
+ m.connected.Store(true)
+
+ require.NoError(t, m.Write(context.Background(), []byte{0x01}))
+ start := time.Now()
+ require.NoError(t, m.Write(context.Background(), []byte{0x02}))
+ assert.GreaterOrEqual(t, time.Since(start), 40*time.Millisecond, "second write must wait out the gap")
+}
diff --git a/plc4go/spi/transports/serial/Transport_test.go b/plc4go/spi/transports/serial/Transport_test.go
index f9af03e011..e996e28579 100644
--- a/plc4go/spi/transports/serial/Transport_test.go
+++ b/plc4go/spi/transports/serial/Transport_test.go
@@ -38,7 +38,8 @@ func TestNewTransport(t *testing.T) {
{
name: "create it",
want: &Transport{
- log: log.Logger,
+ registry: newSharedPortRegistry(log.Logger),
+ log: log.Logger,
},
},
}
diff --git a/plc4go/spi/transports/serial/deadline_reader.go b/plc4go/spi/transports/serial/deadline_reader.go
index 78e6cd5080..97b3c6f3e4 100644
--- a/plc4go/spi/transports/serial/deadline_reader.go
+++ b/plc4go/spi/transports/serial/deadline_reader.go
@@ -37,11 +37,12 @@ import (
type deadlineReader struct {
port serialport.Port
fallback time.Duration
+ activity *pacer // notified on successful reads; may be nil
explicit atomic.Value // time.Time; zero value = none
}
-func newDeadlineReader(port serialport.Port, fallback time.Duration) *deadlineReader {
- r := &deadlineReader{port: port, fallback: fallback}
+func newDeadlineReader(port serialport.Port, fallback time.Duration, activity *pacer) *deadlineReader {
+ r := &deadlineReader{port: port, fallback: fallback, activity: activity}
r.explicit.Store(time.Time{})
return r
}
@@ -76,5 +77,9 @@ func (r *deadlineReader) Read(p []byte) (int, error) {
return 0, err
}
}
- return r.port.Read(p)
+ n, err := r.port.Read(p)
+ if n > 0 {
+ r.activity.noteActivity()
+ }
+ return n, err
}
diff --git a/plc4go/spi/transports/serial/deadline_reader_test.go b/plc4go/spi/transports/serial/deadline_reader_test.go
index cb5aa3e247..92872b2ee5 100644
--- a/plc4go/spi/transports/serial/deadline_reader_test.go
+++ b/plc4go/spi/transports/serial/deadline_reader_test.go
@@ -40,7 +40,7 @@ func (r *recordingPort) SetReadDeadline(t time.Time) error {
func TestDeadlineReader_FallbackArmsRelativeDeadline(t *testing.T) {
port := &recordingPort{}
- reader := newDeadlineReader(port, 200*time.Millisecond)
+ reader := newDeadlineReader(port, 200*time.Millisecond, nil)
before := time.Now()
_, err := reader.Read(make([]byte, 1))
@@ -54,7 +54,7 @@ func TestDeadlineReader_FallbackArmsRelativeDeadline(t *testing.T) {
func TestDeadlineReader_ZeroFallbackClearsDeadline(t *testing.T) {
port := &recordingPort{}
- reader := newDeadlineReader(port, 0)
+ reader := newDeadlineReader(port, 0, nil)
_, err := reader.Read(make([]byte, 1))
require.NoError(t, err)
@@ -65,7 +65,7 @@ func TestDeadlineReader_ZeroFallbackClearsDeadline(t *testing.T) {
func TestDeadlineReader_ExplicitDeadlineWins(t *testing.T) {
port := &recordingPort{}
- reader := newDeadlineReader(port, time.Hour)
+ reader := newDeadlineReader(port, time.Hour, nil)
explicit := time.Now().Add(30 * time.Millisecond)
reader.setExplicitDeadline(explicit)
@@ -78,7 +78,7 @@ func TestDeadlineReader_ExplicitDeadlineWins(t *testing.T) {
func TestDeadlineReader_ExpiredExplicitHonoredOnceThenFallback(t *testing.T) {
port := &recordingPort{}
- reader := newDeadlineReader(port, time.Hour)
+ reader := newDeadlineReader(port, time.Hour, nil)
expired := time.Now().Add(-time.Second)
reader.setExplicitDeadline(expired)
@@ -98,7 +98,7 @@ func TestDeadlineReader_ExpiredExplicitHonoredOnceThenFallback(t *testing.T) {
func TestDeadlineReader_ClearingExplicitRestoresFallback(t *testing.T) {
port := &recordingPort{}
- reader := newDeadlineReader(port, time.Minute)
+ reader := newDeadlineReader(port, time.Minute, nil)
reader.setExplicitDeadline(time.Now().Add(time.Hour))
_, _ = reader.Read(make([]byte, 1))
diff --git a/plc4go/spi/transports/serial/options.go b/plc4go/spi/transports/serial/options.go
index 82bd9f34d4..dc44ceaf54 100644
--- a/plc4go/spi/transports/serial/options.go
+++ b/plc4go/spi/transports/serial/options.go
@@ -42,6 +42,13 @@ type serialConfig struct {
// 0 means no write timeout.
writeTimeout time.Duration
connectTimeout uint32 // milliseconds
+ // reusePort shares one physical port between transport instances with
+ // identical configuration (broadcast reads, serialized paced writes).
+ reusePort bool
+ // interframeDelay is the minimum silence enforced before each write,
+ // measured from the later of last-write-end and last-received-byte.
+ // 0 disables pacing. Works on shared and dedicated ports alike.
+ interframeDelay time.Duration
}
func defaultSerialConfig() serialConfig {
@@ -147,6 +154,20 @@ func parseSerialOptions(options map[string][]string) (serialConfig, error) {
}
cfg.connectTimeout = uint32(millis)
}
+ if raw, ok := firstValue(options, "reuse-port"); ok {
+ value, err := strconv.ParseBool(raw)
+ if err != nil {
+ return cfg, optionError("reuse-port", raw, "must be true or false")
+ }
+ cfg.reusePort = value
+ }
+ if raw, ok := firstValue(options, "interframe-delay"); ok {
+ millis, err := strconv.ParseUint(raw, 10, 32)
+ if err != nil {
+ return cfg, optionError("interframe-delay", raw, "must be a non-negative integer (milliseconds)")
+ }
+ cfg.interframeDelay = time.Duration(millis) * time.Millisecond
+ }
return cfg, nil
}
diff --git a/plc4go/spi/transports/serial/options_test.go b/plc4go/spi/transports/serial/options_test.go
index 5c22ad6253..b0a7afb606 100644
--- a/plc4go/spi/transports/serial/options_test.go
+++ b/plc4go/spi/transports/serial/options_test.go
@@ -144,6 +144,34 @@ func TestParseSerialOptions(t *testing.T) {
options: map[string][]string{"break-enabled": {"true"}, "no-such-thing": {"1"}},
want: defaultSerialConfig(),
},
+ {
+ name: "reuse-port accepted",
+ options: map[string][]string{"reuse-port": {"true"}},
+ want: func() serialConfig {
+ c := defaultSerialConfig()
+ c.reusePort = true
+ return c
+ }(),
+ },
+ {
+ name: "interframe-delay accepted",
+ options: map[string][]string{"interframe-delay": {"50"}},
+ want: func() serialConfig {
+ c := defaultSerialConfig()
+ c.interframeDelay = 50 * time.Millisecond
+ return c
+ }(),
+ },
+ {
+ name: "invalid reuse-port",
+ options: map[string][]string{"reuse-port": {"maybe"}},
+ wantErr: `"reuse-port"`,
+ },
+ {
+ name: "invalid interframe-delay",
+ options: map[string][]string{"interframe-delay": {"-1"}},
+ wantErr: `"interframe-delay"`,
+ },
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
diff --git a/plc4go/spi/transports/serial/pacer.go b/plc4go/spi/transports/serial/pacer.go
new file mode 100644
index 0000000000..cf28671527
--- /dev/null
+++ b/plc4go/spi/transports/serial/pacer.go
@@ -0,0 +1,77 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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
+ *
+ * https://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 serial
+
+import (
+ "os"
+ "sync"
+ "time"
+)
+
+// pacer enforces a minimum silence gap before writes on a serial line,
+// measured from the later of the last write end and the last observed
+// read activity (RTU t3.5-style semantics). A nil pacer or a zero delay
+// disables pacing entirely. A pacer only tracks timestamps — it does not
+// serialize concurrent writers; callers must hold their own write lock
+// around waitTurn+write for the gap guarantee to hold.
+type pacer struct {
+ delay time.Duration
+ mu sync.Mutex
+ last time.Time
+}
+
+func newPacer(delay time.Duration) *pacer {
+ return &pacer{delay: delay}
+}
+
+// noteActivity records line activity (a completed write or received data).
+func (p *pacer) noteActivity() {
+ if p == nil || p.delay <= 0 {
+ return
+ }
+ p.mu.Lock()
+ if now := time.Now(); now.After(p.last) {
+ p.last = now
+ }
+ p.mu.Unlock()
+}
+
+// waitTurn sleeps until the configured gap since the last activity has
+// elapsed. A non-zero deadline bounds the wait: if it would expire before
+// the gap does, waitTurn returns os.ErrDeadlineExceeded without sleeping
+// the gap out.
+func (p *pacer) waitTurn(deadline time.Time) error {
+ if p == nil || p.delay <= 0 {
+ return nil
+ }
+ for {
+ p.mu.Lock()
+ ready := p.last.Add(p.delay)
+ p.mu.Unlock()
+ wait := time.Until(ready)
+ if wait <= 0 {
+ return nil
+ }
+ if !deadline.IsZero() && ready.After(deadline) {
+ return os.ErrDeadlineExceeded
+ }
+ time.Sleep(wait)
+ }
+}
diff --git a/plc4go/spi/transports/serial/pacer_test.go b/plc4go/spi/transports/serial/pacer_test.go
new file mode 100644
index 0000000000..acae8f5312
--- /dev/null
+++ b/plc4go/spi/transports/serial/pacer_test.go
@@ -0,0 +1,80 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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
+ *
+ * https://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 serial
+
+import (
+ "os"
+ "testing"
+ "time"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestPacer_NilAndZeroDelayAreNoops(t *testing.T) {
+ var nilPacer *pacer
+ nilPacer.noteActivity()
+ require.NoError(t, nilPacer.waitTurn(time.Time{}))
+
+ zero := newPacer(0)
+ zero.noteActivity()
+ start := time.Now()
+ require.NoError(t, zero.waitTurn(time.Time{}))
+ assert.Less(t, time.Since(start), 20*time.Millisecond)
+}
+
+func TestPacer_EnforcesGapAfterActivity(t *testing.T) {
+ p := newPacer(60 * time.Millisecond)
+ p.noteActivity()
+ start := time.Now()
+ require.NoError(t, p.waitTurn(time.Time{}))
+ assert.GreaterOrEqual(t, time.Since(start), 50*time.Millisecond, "must wait out the gap")
+}
+
+func TestPacer_NoWaitWhenGapAlreadyElapsed(t *testing.T) {
+ p := newPacer(30 * time.Millisecond)
+ p.noteActivity()
+ time.Sleep(40 * time.Millisecond)
+ start := time.Now()
+ require.NoError(t, p.waitTurn(time.Time{}))
+ assert.Less(t, time.Since(start), 20*time.Millisecond)
+}
+
+func TestPacer_DeadlineShorterThanGapFailsFast(t *testing.T) {
+ p := newPacer(500 * time.Millisecond)
+ p.noteActivity()
+ start := time.Now()
+ err := p.waitTurn(time.Now().Add(20 * time.Millisecond))
+ require.ErrorIs(t, err, os.ErrDeadlineExceeded)
+ assert.Less(t, time.Since(start), 200*time.Millisecond, "must not sleep out the full gap")
+}
+
+func TestPacer_ActivityDuringWaitExtendsGap(t *testing.T) {
+ p := newPacer(80 * time.Millisecond)
+ p.noteActivity()
+ go func() {
+ time.Sleep(40 * time.Millisecond)
+ p.noteActivity() // traffic arrives while a writer is waiting its turn
+ }()
+ start := time.Now()
+ require.NoError(t, p.waitTurn(time.Time{}))
+ assert.GreaterOrEqual(t, time.Since(start), 110*time.Millisecond,
+ "the gap must restart from the mid-wait activity (40ms + 80ms)")
+}
diff --git a/plc4go/spi/transports/serial/ring_buffer.go b/plc4go/spi/transports/serial/ring_buffer.go
new file mode 100644
index 0000000000..40400bc555
--- /dev/null
+++ b/plc4go/spi/transports/serial/ring_buffer.go
@@ -0,0 +1,173 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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
+ *
+ * https://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 serial
+
+import (
+ "os"
+ "sync"
+ "time"
+)
+
+// byteRing is a bounded FIFO byte buffer connecting the shared-port reader
+// (append side) to one subscription (read side). On overflow the OLDEST
+// bytes are dropped — a slow subscriber loses history but can never block
+// the shared reader; protocol codecs resynchronize on the resulting gap.
+//
+// Contract: exactly one goroutine blocks in read at a time (wake-ups are
+// coalesced through a one-slot channel).
+type byteRing struct {
+ mu sync.Mutex
+ buf []byte
+ start int
+ length int
+ dropped uint64
+ closed bool
+ err error
+ notify chan struct{}
+}
+
+func newByteRing(capacity int) *byteRing {
+ return &byteRing{
+ buf: make([]byte, capacity),
+ notify: make(chan struct{}, 1),
+ }
+}
+
+func (r *byteRing) signal() {
+ select {
+ case r.notify <- struct{}{}:
+ default:
+ }
+}
+
+// append copies p into the ring, dropping the oldest bytes when capacity
+// is exceeded, and returns how many bytes were dropped. Appends after
+// close are discarded.
+func (r *byteRing) append(p []byte) int {
+ r.mu.Lock()
+ if r.closed || len(p) == 0 {
+ r.mu.Unlock()
+ return 0
+ }
+ dropped := 0
+ if len(p) >= len(r.buf) {
+ dropped = r.length + len(p) - len(r.buf)
+ p = p[len(p)-len(r.buf):]
+ r.start, r.length = 0, 0
+ } else if over := r.length + len(p) - len(r.buf); over > 0 {
+ dropped = over
+ r.start = (r.start + over) % len(r.buf)
+ r.length -= over
+ }
+ for i := range p {
+ r.buf[(r.start+r.length+i)%len(r.buf)] = p[i]
+ }
+ r.length += len(p)
+ r.dropped += uint64(dropped)
+ r.mu.Unlock()
+ r.signal()
+ return dropped
+}
+
+// fail records a fatal error. Buffered data remains readable; once it is
+// drained, reads return err.
+func (r *byteRing) fail(err error) {
+ r.mu.Lock()
+ if r.err == nil {
+ r.err = err
+ }
+ r.mu.Unlock()
+ r.signal()
+}
+
+// close makes all subsequent reads fail with os.ErrClosed (buffered data
+// is NOT drained first — matching a closed port's behavior).
+func (r *byteRing) close() {
+ r.mu.Lock()
+ r.closed = true
+ r.mu.Unlock()
+ r.signal()
+}
+
+func (r *byteRing) isClosed() bool {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ return r.closed
+}
+
+func (r *byteRing) droppedTotal() uint64 {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ return r.dropped
+}
+
+// read blocks until data is available, the deadline expires
+// (os.ErrDeadlineExceeded; immediately if already past), the ring is
+// closed (os.ErrClosed), or a recorded failure surfaces after the buffer
+// drains. A zero deadline blocks indefinitely.
+func (r *byteRing) read(p []byte, deadline time.Time) (int, error) {
+ if len(p) == 0 {
+ return 0, nil
+ }
+ var timeout <-chan time.Time
+ if !deadline.IsZero() {
+ wait := time.Until(deadline)
+ if wait <= 0 {
+ r.mu.Lock()
+ closed := r.closed
+ r.mu.Unlock()
+ if closed {
+ return 0, os.ErrClosed
+ }
+ return 0, os.ErrDeadlineExceeded
+ }
+ timer := time.NewTimer(wait)
+ defer timer.Stop()
+ timeout = timer.C
+ }
+ for {
+ r.mu.Lock()
+ if r.closed {
+ r.mu.Unlock()
+ return 0, os.ErrClosed
+ }
+ if r.length > 0 {
+ n := min(len(p), r.length)
+ for i := 0; i < n; i++ {
+ p[i] = r.buf[(r.start+i)%len(r.buf)]
+ }
+ r.start = (r.start + n) % len(r.buf)
+ r.length -= n
+ r.mu.Unlock()
+ return n, nil
+ }
+ if r.err != nil {
+ err := r.err
+ r.mu.Unlock()
+ return 0, err
+ }
+ r.mu.Unlock()
+ select {
+ case <-r.notify:
+ case <-timeout:
+ return 0, os.ErrDeadlineExceeded
+ }
+ }
+}
diff --git a/plc4go/spi/transports/serial/ring_buffer_test.go b/plc4go/spi/transports/serial/ring_buffer_test.go
new file mode 100644
index 0000000000..556b3d1478
--- /dev/null
+++ b/plc4go/spi/transports/serial/ring_buffer_test.go
@@ -0,0 +1,122 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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
+ *
+ * https://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 serial
+
+import (
+ "os"
+ "testing"
+ "time"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/apache/plc4x/plc4go/spi/errors"
+)
+
+func TestByteRing_FIFOAndWraparound(t *testing.T) {
+ r := newByteRing(8)
+ assert.Zero(t, r.append([]byte("abcde")))
+ buf := make([]byte, 3)
+ n, err := r.read(buf, time.Time{})
+ require.NoError(t, err)
+ assert.Equal(t, "abc", string(buf[:n]))
+ // wraps around the 8-byte capacity
+ assert.Zero(t, r.append([]byte("fghi")))
+ got := make([]byte, 0, 6)
+ for len(got) < 6 {
+ n, err = r.read(buf, time.Time{})
+ require.NoError(t, err)
+ got = append(got, buf[:n]...)
+ }
+ assert.Equal(t, "defghi", string(got))
+}
+
+func TestByteRing_BlockingReadWokenByAppend(t *testing.T) {
+ r := newByteRing(8)
+ go func() {
+ time.Sleep(20 * time.Millisecond)
+ r.append([]byte{0x42})
+ }()
+ buf := make([]byte, 1)
+ n, err := r.read(buf, time.Now().Add(5*time.Second))
+ require.NoError(t, err)
+ require.Equal(t, 1, n)
+ assert.Equal(t, byte(0x42), buf[0])
+}
+
+func TestByteRing_DeadlineExpiry(t *testing.T) {
+ r := newByteRing(8)
+ start := time.Now()
+ _, err := r.read(make([]byte, 1), time.Now().Add(40*time.Millisecond))
+ require.ErrorIs(t, err, os.ErrDeadlineExceeded)
+ assert.GreaterOrEqual(t, time.Since(start), 40*time.Millisecond)
+
+ // already-expired deadline errors immediately, even with data buffered
+ r.append([]byte{0x01})
+ _, err = r.read(make([]byte, 1), time.Now().Add(-time.Second))
+ require.ErrorIs(t, err, os.ErrDeadlineExceeded)
+}
+
+func TestByteRing_DropOldestOnOverflow(t *testing.T) {
+ r := newByteRing(4)
+ assert.Zero(t, r.append([]byte("ab")))
+ assert.Equal(t, 2, r.append([]byte("cdef")), "two oldest bytes dropped")
+ assert.EqualValues(t, 2, r.droppedTotal())
+ buf := make([]byte, 4)
+ n, err := r.read(buf, time.Time{})
+ require.NoError(t, err)
+ assert.Equal(t, "cdef", string(buf[:n]))
+
+ // a chunk larger than capacity keeps only its tail
+ dropped := r.append([]byte("0123456789"))
+ assert.Equal(t, 6, dropped)
+ n, err = r.read(buf, time.Time{})
+ require.NoError(t, err)
+ assert.Equal(t, "6789", string(buf[:n]))
+}
+
+func TestByteRing_CloseBeatsBufferedData(t *testing.T) {
+ r := newByteRing(8)
+ r.append([]byte("data"))
+ r.close()
+ assert.True(t, r.isClosed())
+ _, err := r.read(make([]byte, 4), time.Time{})
+ require.ErrorIs(t, err, os.ErrClosed)
+}
+
+func TestByteRing_FailDrainsDataThenSurfacesError(t *testing.T) {
+ r := newByteRing(8)
+ r.append([]byte("ok"))
+ portErr := errors.New("port exploded")
+ r.fail(portErr)
+ buf := make([]byte, 8)
+ n, err := r.read(buf, time.Time{})
+ require.NoError(t, err, "buffered data drains before the error")
+ assert.Equal(t, "ok", string(buf[:n]))
+ _, err = r.read(buf, time.Time{})
+ require.ErrorContains(t, err, "port exploded")
+}
+
+func TestByteRing_ClosedBeatsExpiredDeadline(t *testing.T) {
+ r := newByteRing(8)
+ r.close()
+ _, err := r.read(make([]byte, 1), time.Now().Add(-time.Second))
+ require.ErrorIs(t, err, os.ErrClosed, "closed must take precedence over an expired deadline")
+}
diff --git a/plc4go/spi/transports/serial/shared_port.go b/plc4go/spi/transports/serial/shared_port.go
new file mode 100644
index 0000000000..4bc01762dd
--- /dev/null
+++ b/plc4go/spi/transports/serial/shared_port.go
@@ -0,0 +1,337 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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
+ *
+ * https://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 serial
+
+import (
+ "os"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/rs/zerolog"
+
+ "github.com/apache/plc4x/plc4go/spi/errors"
+ "github.com/apache/plc4x/plc4go/spi/transports"
+ "github.com/apache/plc4x/plc4go/spi/transports/serial/serialport"
+)
+
+const (
+ sharedSubscriberBufferCapacity = 64 << 10
+ sharedReaderSlice = 100 * time.Millisecond
+ sharedReaderChunk = 4096
+)
+
+// sharedPortConfig is the full tuple that must be identical for two
+// connections to share one physical port. It is comparable by design.
+type sharedPortConfig struct {
+ port serialport.Config
+ dtr bool
+ rts bool
+ interframeDelay time.Duration
+}
+
+// sharedPortRegistry tracks the shared ports of one Transport. It is not
+// global: sharing works within one driver manager; separate managers
+// opening the same device remain unsupported (as without sharing).
+type sharedPortRegistry struct {
+ mu sync.Mutex
+ ports map[string]*sharedPort
+ bufferCapacity int // per-subscriber ring size; overridable in tests
+ log zerolog.Logger
+}
+
+func newSharedPortRegistry(log zerolog.Logger) *sharedPortRegistry {
+ return &sharedPortRegistry{
+ ports: map[string]*sharedPort{},
+ bufferCapacity: sharedSubscriberBufferCapacity,
+ log: log,
+ }
+}
+
+// acquire joins the existing shared port (config must match exactly) or
+// opens the device and starts its reader.
+func (r *sharedPortRegistry) acquire(portName string, cfg sharedPortConfig) (serialport.Port, error) {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ if existing, ok := r.ports[portName]; ok {
+ if existing.cfg != cfg {
+ return nil, errors.Errorf(
+ "serial port %s is already shared with a different configuration (existing: %+v, requested: %+v)",
+ portName, existing.cfg, cfg)
+ }
+ if sub, ok := existing.subscribe(r.bufferCapacity); ok {
+ return sub, nil
+ }
+ // The entry closed concurrently; drop it and open fresh below.
+ delete(r.ports, portName)
+ }
+ port, err := serialport.Open(portName, cfg.port)
+ if err != nil {
+ return nil, errors.Wrap(err, "error opening shared serial port")
+ }
+ applySharedModemLines(port, cfg, r.log)
+ sp := &sharedPort{
+ registry: r,
+ portName: portName,
+ cfg: cfg,
+ port: port,
+ pacer: newPacer(cfg.interframeDelay),
+ log: r.log,
+ }
+ r.ports[portName] = sp
+ sub, ok := sp.subscribe(r.bufferCapacity)
+ if !ok {
+ // Cannot happen: the port was created closed==false and nothing
+ // else references it yet.
+ delete(r.ports, portName)
+ _ = port.Close()
+ return nil, errors.New("serialport: freshly opened shared port already closed")
+ }
+ go sp.readLoop()
+ return sub, nil
+}
+
+// remove deletes the registry entry if it still maps to sp.
+func (r *sharedPortRegistry) remove(sp *sharedPort) {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ if r.ports[sp.portName] == sp {
+ delete(r.ports, sp.portName)
+ }
+}
+
+// applySharedModemLines asserts DTR/RTS once at open, mirroring the
+// dedicated path's warn-don't-fail semantics.
+func applySharedModemLines(port serialport.Port, cfg sharedPortConfig, log zerolog.Logger) {
+ controlPort, ok := port.(serialport.ControlPort)
+ if !ok {
+ return
+ }
+ if cfg.dtr {
+ if err := controlPort.SetDTR(true); err != nil {
+ log.Warn().Err(err).Msg("could not assert DTR on shared port")
+ }
+ }
+ if cfg.rts {
+ if err := controlPort.SetRTS(true); err != nil {
+ log.Warn().Err(err).Msg("could not assert RTS on shared port")
+ }
+ }
+}
+
+// sharedPort owns one physical port: a broadcast reader, the subscriber
+// list, and the serialized paced write path.
+//
+// Locking: stateMu guards subs/closed; writeMu serializes writers. writeMu may
+// acquire stateMu momentarily (via isClosed) but never the reverse — the nesting
+// is strictly one-directional, so no cycle is possible. Never hold stateMu while
+// taking registry.mu; on last-unsubscribe the physical port is closed BEFORE the
+// registry entry is removed, so a concurrent acquire either joins a live port or
+// re-opens a fully released device.
+type sharedPort struct {
+ registry *sharedPortRegistry
+ portName string
+ cfg sharedPortConfig
+ port serialport.Port
+ pacer *pacer
+ log zerolog.Logger
+
+ stateMu sync.Mutex
+ subs []*byteRing
+ closed bool
+
+ writeMu sync.Mutex
+}
+
+// subscribe adds a subscriber; ok is false when the port already closed.
+func (sp *sharedPort) subscribe(capacity int) (*subscription, bool) {
+ sp.stateMu.Lock()
+ defer sp.stateMu.Unlock()
+ if sp.closed {
+ return nil, false
+ }
+ ring := newByteRing(capacity)
+ sp.subs = append(sp.subs, ring)
+ sub := &subscription{sp: sp, ring: ring}
+ sub.readDeadline.Store(time.Time{})
+ sub.writeDeadline.Store(time.Time{})
+ return sub, true
+}
+
+func (sp *sharedPort) isClosed() bool {
+ sp.stateMu.Lock()
+ defer sp.stateMu.Unlock()
+ return sp.closed
+}
+
+// unsubscribe detaches ring; the last subscriber closes the port.
+func (sp *sharedPort) unsubscribe(ring *byteRing) error {
+ ring.close()
+ sp.stateMu.Lock()
+ for i, s := range sp.subs {
+ if s == ring {
+ sp.subs = append(sp.subs[:i], sp.subs[i+1:]...)
+ break
+ }
+ }
+ last := len(sp.subs) == 0 && !sp.closed
+ if last {
+ sp.closed = true
+ }
+ sp.stateMu.Unlock()
+ if !last {
+ return nil
+ }
+ err := sp.port.Close() // unblocks the reader; close before unmapping
+ sp.registry.remove(sp)
+ return err
+}
+
+// fail propagates a fatal port error to all subscribers and evicts the
+// port so a reconnect re-opens the device.
+func (sp *sharedPort) fail(err error) {
+ sp.log.Warn().Err(err).Str("port", sp.portName).Msg("shared serial port failed")
+ sp.stateMu.Lock()
+ alreadyClosed := sp.closed
+ sp.closed = true
+ subs := sp.subs
+ sp.subs = nil
+ sp.stateMu.Unlock()
+ for _, ring := range subs {
+ ring.fail(err)
+ }
+ if !alreadyClosed {
+ _ = sp.port.Close()
+ }
+ sp.registry.remove(sp)
+}
+
+// readLoop broadcasts everything the port delivers into every
+// subscriber's ring. Deadline slices keep shutdown prompt.
+func (sp *sharedPort) readLoop() {
+ buf := make([]byte, sharedReaderChunk)
+ warnedDrops := map[*byteRing]uint64{}
+ for {
+ if sp.isClosed() {
+ return
+ }
+ _ = sp.port.SetReadDeadline(time.Now().Add(sharedReaderSlice))
+ n, err := sp.port.Read(buf)
+ if n > 0 {
+ sp.pacer.noteActivity()
+ sp.stateMu.Lock()
+ subs := append([]*byteRing(nil), sp.subs...)
+ sp.stateMu.Unlock()
+ for _, ring := range subs {
+ if dropped := ring.append(buf[:n]); dropped > 0 {
+ total := ring.droppedTotal()
+ if last := warnedDrops[ring]; last == 0 || total >= 2*last {
+ warnedDrops[ring] = total
+ sp.log.Warn().
+ Int("dropped", dropped).
+ Uint64("totalDropped", total).
+ Str("port", sp.portName).
+ Msg("shared serial subscriber buffer overflow, oldest bytes dropped")
+ }
+ }
+ }
+ }
+ if err != nil && !transports.ErrorIs(err, os.ErrDeadlineExceeded) {
+ if sp.isClosed() {
+ return // expected: the last unsubscribe closed the port
+ }
+ sp.fail(err)
+ return
+ }
+ }
+}
+
+// write serializes and paces writes from all subscribers.
+func (sp *sharedPort) write(ring *byteRing, p []byte, deadline time.Time) (int, error) {
+ sp.writeMu.Lock()
+ defer sp.writeMu.Unlock()
+ // The subscription may close while a Write is waiting on writeMu; recheck under the lock
+ // so a closed connection's bytes never reach the shared line.
+ if ring.isClosed() {
+ return 0, os.ErrClosed
+ }
+ if sp.isClosed() {
+ return 0, os.ErrClosed
+ }
+ if err := sp.pacer.waitTurn(deadline); err != nil {
+ return 0, err
+ }
+ if err := sp.port.SetWriteDeadline(deadline); err != nil {
+ return 0, err
+ }
+ n, err := sp.port.Write(p)
+ sp.pacer.noteActivity()
+ return n, err
+}
+
+// subscription is one connection's view of a shared port. It implements
+// serialport.Port (and deliberately NOT serialport.ControlPort — modem
+// line changes would cross-talk between connections).
+type subscription struct {
+ sp *sharedPort
+ ring *byteRing
+ readDeadline atomic.Value // time.Time
+ writeDeadline atomic.Value // time.Time
+ closeOnce sync.Once
+ closeErr error
+}
+
+var _ serialport.Port = (*subscription)(nil)
+
+func (s *subscription) Read(p []byte) (int, error) {
+ deadline, _ := s.readDeadline.Load().(time.Time)
+ return s.ring.read(p, deadline)
+}
+
+func (s *subscription) Write(p []byte) (int, error) {
+ if s.ring.isClosed() {
+ return 0, os.ErrClosed
+ }
+ deadline, _ := s.writeDeadline.Load().(time.Time)
+ return s.sp.write(s.ring, p, deadline)
+}
+
+func (s *subscription) SetReadDeadline(t time.Time) error {
+ if s.ring.isClosed() {
+ return os.ErrClosed
+ }
+ s.readDeadline.Store(t)
+ return nil
+}
+
+func (s *subscription) SetWriteDeadline(t time.Time) error {
+ if s.ring.isClosed() {
+ return os.ErrClosed
+ }
+ s.writeDeadline.Store(t)
+ return nil
+}
+
+func (s *subscription) Close() error {
+ s.closeOnce.Do(func() {
+ s.closeErr = s.sp.unsubscribe(s.ring)
+ })
+ return s.closeErr
+}
diff --git a/plc4go/spi/transports/serial/shared_port_pty_test.go b/plc4go/spi/transports/serial/shared_port_pty_test.go
new file mode 100644
index 0000000000..3ab510282d
--- /dev/null
+++ b/plc4go/spi/transports/serial/shared_port_pty_test.go
@@ -0,0 +1,175 @@
+//go:build linux
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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
+ *
+ * https://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 serial
+
+import (
+ "os"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/rs/zerolog"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/apache/plc4x/plc4go/spi/transports/serial/serialport"
+)
+
+func acquireTwo(t *testing.T, registry *sharedPortRegistry, slavePath string, cfg sharedPortConfig) (serialport.Port, serialport.Port) {
+ t.Helper()
+ first, err := registry.acquire(slavePath, cfg)
+ require.NoError(t, err)
+ second, err := registry.acquire(slavePath, cfg)
+ require.NoError(t, err)
+ return first, second
+}
+
+func TestSharedPort_BroadcastToAllSubscribers(t *testing.T) {
+ master, slavePath := openPTY(t)
+ registry := newSharedPortRegistry(zerolog.Nop())
+ cfg := sharedPortConfig{port: serialport.Config{BaudRate: 9600}}
+ first, second := acquireTwo(t, registry, slavePath, cfg)
+ defer first.Close()
+ defer second.Close()
+
+ _, err := master.Write([]byte("hello"))
+ require.NoError(t, err)
+
+ for _, sub := range []serialport.Port{first, second} {
+ require.NoError(t, sub.SetReadDeadline(time.Now().Add(5*time.Second)))
+ buf := make([]byte, 16)
+ n, err := sub.Read(buf)
+ require.NoError(t, err)
+ assert.Equal(t, "hello", string(buf[:n]), "every subscriber sees the full traffic")
+ }
+}
+
+func TestSharedPort_WritesSerializedAndPaced(t *testing.T) {
+ master, slavePath := openPTY(t)
+ registry := newSharedPortRegistry(zerolog.Nop())
+ cfg := sharedPortConfig{port: serialport.Config{BaudRate: 9600}, interframeDelay: 60 * time.Millisecond}
+ first, second := acquireTwo(t, registry, slavePath, cfg)
+ defer first.Close()
+ defer second.Close()
+
+ start := time.Now()
+ var wg sync.WaitGroup
+ for _, sub := range []serialport.Port{first, second} {
+ wg.Add(1)
+ go func(p serialport.Port) {
+ defer wg.Done()
+ _, err := p.Write([]byte("XXXX"))
+ assert.NoError(t, err)
+ }(sub)
+ }
+ wg.Wait()
+ elapsed := time.Since(start)
+
+ buf := make([]byte, 8)
+ total := 0
+ for total < 8 {
+ n, err := master.Read(buf[total:])
+ require.NoError(t, err)
+ total += n
+ }
+ assert.Equal(t, "XXXXXXXX", string(buf), "both payloads intact")
+ assert.GreaterOrEqual(t, elapsed, 60*time.Millisecond, "second write must wait out the inter-frame gap")
+}
+
+func TestSharedPort_ConfigMismatchFails(t *testing.T) {
+ _, slavePath := openPTY(t)
+ registry := newSharedPortRegistry(zerolog.Nop())
+ first, err := registry.acquire(slavePath, sharedPortConfig{port: serialport.Config{BaudRate: 9600}})
+ require.NoError(t, err)
+ defer first.Close()
+
+ _, err = registry.acquire(slavePath, sharedPortConfig{port: serialport.Config{BaudRate: 19200}})
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), slavePath)
+}
+
+func TestSharedPort_RefcountLifecycle(t *testing.T) {
+ master, slavePath := openPTY(t)
+ registry := newSharedPortRegistry(zerolog.Nop())
+ cfg := sharedPortConfig{port: serialport.Config{BaudRate: 9600}}
+ first, second := acquireTwo(t, registry, slavePath, cfg)
+
+ // First close: the second subscriber keeps working.
+ require.NoError(t, first.Close())
+ _, err := master.Write([]byte{0x01})
+ require.NoError(t, err)
+ require.NoError(t, second.SetReadDeadline(time.Now().Add(5*time.Second)))
+ buf := make([]byte, 1)
+ _, err = second.Read(buf)
+ require.NoError(t, err)
+
+ // Reads on the closed subscription fail with os.ErrClosed.
+ _, err = first.Read(buf)
+ require.ErrorIs(t, err, os.ErrClosed)
+
+ // Last close releases the port; a fresh acquire re-opens it.
+ require.NoError(t, second.Close())
+ third, err := registry.acquire(slavePath, cfg)
+ require.NoError(t, err)
+ require.NoError(t, third.Close())
+}
+
+func TestSharedPort_OverflowDropsOldest(t *testing.T) {
+ master, slavePath := openPTY(t)
+ registry := newSharedPortRegistry(zerolog.Nop())
+ registry.bufferCapacity = 8 // tiny buffer to force overflow
+ cfg := sharedPortConfig{port: serialport.Config{BaudRate: 9600}}
+ sub, err := registry.acquire(slavePath, cfg)
+ require.NoError(t, err)
+ defer sub.Close()
+
+ _, err = master.Write([]byte("0123456789ABCDEF"))
+ require.NoError(t, err)
+
+ // Wait for delivery, then confirm reads still work and end with the
+ // freshest bytes (drop-oldest, never drop-newest).
+ require.NoError(t, sub.SetReadDeadline(time.Now().Add(5*time.Second)))
+ collected := make([]byte, 0, 16)
+ buf := make([]byte, 16)
+ for {
+ require.NoError(t, sub.SetReadDeadline(time.Now().Add(200*time.Millisecond)))
+ n, err := sub.Read(buf)
+ if err != nil {
+ break // deadline: stream drained
+ }
+ collected = append(collected, buf[:n]...)
+ }
+ require.NotEmpty(t, collected)
+ assert.Equal(t, byte('F'), collected[len(collected)-1], "newest byte must survive")
+ assert.LessOrEqual(t, len(collected), 16)
+ assert.Positive(t, sub.(*subscription).ring.droppedTotal(), "drop counter must have risen")
+}
+
+func TestSharedPort_SubscriptionIsNotControlPort(t *testing.T) {
+ _, slavePath := openPTY(t)
+ registry := newSharedPortRegistry(zerolog.Nop())
+ sub, err := registry.acquire(slavePath, sharedPortConfig{port: serialport.Config{BaudRate: 9600}})
+ require.NoError(t, err)
+ defer sub.Close()
+ _, isControl := sub.(serialport.ControlPort)
+ assert.False(t, isControl, "modem control must not leak through shared subscriptions")
+}