Add journal buffer system for race-condition-free plugin writes

[thiagoralves]

Summary

This PR implements a journal buffer system that provides race-condition-free writes to OpenPLC image tables from multiple plugins. The journal buffer is applied atomically at the start of each PLC scan cycle with "last writer wins" semantics.

Key Changes

• Phase 1: Core journal buffer C implementation (journal_buffer.c/.h)

  • Static buffer with 1024 entries (~20KB)
  • Thread-safe write functions for all data types (bool, byte, int, dint, lint)
  • Emergency flush when buffer is full
  • Sequence-based ordering for deterministic conflict resolution

• Phase 2: Runtime integration

  • Journal applied at cycle start before plugin hooks
  • Proper initialization and cleanup in PLC lifecycle

• Phase 3: Plugin API extension

  • Journal write functions exposed to native plugins via plugin_runtime_args_t
  • Python plugins use journal through SafeBufferAccess automatically

• Phase 4: S7Comm native plugin migration

  • Removed double-buffering (no longer needed)
  • On-demand data sync via Snap7 RWArea callback
  • Reads: acquire OpenPLC mutex, copy fresh data
  • Writes: use journal (thread-safe, no mutex needed)

• Phase 5: Python plugin optimization

  • Modbus Slave: removed mutex from simple setValues (journal handles thread safety)
  • Kept mutex only for read-modify-write operations

Architecture

Plugins (S7Comm, Modbus, etc.)
         │
         ▼ (writes)
┌─────────────────┐
│  Journal Buffer │  Thread-safe writes with sequence numbers
└────────┬────────┘
         │ (applied at cycle_start)
         ▼
┌─────────────────┐
│  Image Tables   │  Core PLC buffers
└─────────────────┘
         ▲
         │ (reads with mutex)
Plugins read directly

Test plan

• Build successfully on Linux
• PLC runtime starts without errors
• Modbus Slave plugin functions correctly
• Modbus Master plugin functions correctly
• S7Comm plugin initializes and accepts connections
• S7 client reads return correct OpenPLC values
• S7 client writes are applied to OpenPLC buffers
• Multiple plugins can write to same locations without race conditions

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 23 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The chosen value of 1024 entries may not be sufficient for all use cases. Consider adding a comment explaining the rationale behind this buffer size (e.g., expected maximum writes per cycle, memory constraints) and whether it should be configurable.

Suggested change

	* pending entries and make room for new ones.
	*/
	#define JOURNAL_MAX_ENTRIES 1024
	* pending entries and make room for new ones.
	*
	* Rationale:
	* - Typical plugin workloads are expected to issue far fewer than 1024 writes
	* per PLC scan cycle, so this value provides a safety margin while keeping
	* memory usage bounded and predictable.
	* - With journal_entry_t sized for the largest supported value type, this
	* limit keeps the total journal buffer size acceptable for typical embedded
	* targets.
	*
	* Configuration:
	* - The default value is 1024, but it can be overridden at compile time by
	* defining JOURNAL_MAX_ENTRIES (e.g., via compiler flag
	* -DJOURNAL_MAX_ENTRIES=4096) before including this header.
	* - Increasing this value allows more plugin writes per cycle at the cost of
	* higher memory usage.
	*/
	#ifndef JOURNAL_MAX_ENTRIES
	#define JOURNAL_MAX_ENTRIES 1024
	#endif

[Copilot]

After emergency_flush_locked() at line 124, g_count is reset to 0 inside emergency_flush_locked(). However, the function continues to use g_count without rechecking if the emergency flush succeeded. If emergency_flush_locked() fails to acquire the image_mutex or encounters an error, g_count might still be at JOURNAL_MAX_ENTRIES, causing an out-of-bounds array access at line 128. Add error handling or verification after emergency flush.

[Copilot]

Integer division PTag->Start / get_type_size(type) may not correctly handle byte-offset addressing. For example, if PTag->Start is a byte offset that doesn't align with the type size, this calculation will truncate and potentially access the wrong buffer index. Consider adding validation that PTag->Start is properly aligned or handling partial offsets.

[Copilot]

The value masking with '& 0xFF' happens after int() conversion, but if value is negative, int() will preserve the sign and the mask won't produce the expected unsigned byte value. For example, int(-1) & 0xFF = 255, which may be intended, but int(value) where value is a large number could overflow. Consider validating the value range or using ctypes.c_uint8 for proper unsigned conversion.

Suggested change

	result = self.args.journal_write_byte(journal_type, buffer_idx, int(value) & 0xFF)
	result = self.args.journal_write_byte(
	journal_type,
	buffer_idx,
	ctypes.c_uint8(int(value)).value,
	)

[Copilot]

Similar to the byte write issue, these int conversions followed by masking may not handle negative values or out-of-range values correctly. Python's int() can handle arbitrarily large numbers, and masking a large negative number could produce unexpected results. Add explicit range validation before the journal write calls.

Suggested change

	# Handle byte operations
	elif buffer_type_obj.name == "byte":
	result = self.args.journal_write_byte(journal_type, buffer_idx, int(value) & 0xFF)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle int operations (16-bit)
	elif buffer_type_obj.name == "int":
	result = self.args.journal_write_int(journal_type, buffer_idx, int(value) & 0xFFFF)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle dint operations (32-bit)
	elif buffer_type_obj.name == "dint":
	result = self.args.journal_write_dint(journal_type, buffer_idx, int(value) & 0xFFFFFFFF)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle lint operations (64-bit)
	elif buffer_type_obj.name == "lint":
	result = self.args.journal_write_lint(journal_type, buffer_idx, int(value))
	# Handle byte operations (0..255)
	elif buffer_type_obj.name == "byte":
	int_value = int(value)
	if int_value < 0 or int_value > 0xFF:
	raise ValueError(f"Value out of range for byte (0..255): {int_value}")
	result = self.args.journal_write_byte(journal_type, buffer_idx, int_value)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle int operations (16-bit signed, -32768..32767)
	elif buffer_type_obj.name == "int":
	int_value = int(value)
	if int_value < -0x8000 or int_value > 0x7FFF:
	raise ValueError(f"Value out of range for int (-32768..32767): {int_value}")
	result = self.args.journal_write_int(journal_type, buffer_idx, int_value)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle dint operations (32-bit signed, -2147483648..2147483647)
	elif buffer_type_obj.name == "dint":
	int_value = int(value)
	if int_value < -0x80000000 or int_value > 0x7FFFFFFF:
	raise ValueError(
	f"Value out of range for dint (-2147483648..2147483647): {int_value}"
	)
	result = self.args.journal_write_dint(journal_type, buffer_idx, int_value)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle lint operations (64-bit signed, -9223372036854775808..9223372036854775807)
	elif buffer_type_obj.name == "lint":
	int_value = int(value)
	if int_value < -0x8000000000000000 or int_value > 0x7FFFFFFFFFFFFFFF:
	raise ValueError(
	f"Value out of range for lint (-9223372036854775808..9223372036854775807): {int_value}"
	)
	result = self.args.journal_write_lint(journal_type, buffer_idx, int_value)

[Copilot]

Similar to the byte write issue, these int conversions followed by masking may not handle negative values or out-of-range values correctly. Python's int() can handle arbitrarily large numbers, and masking a large negative number could produce unexpected results. Add explicit range validation before the journal write calls.

Suggested change

	# Handle byte operations
	elif buffer_type_obj.name == "byte":
	result = self.args.journal_write_byte(journal_type, buffer_idx, int(value) & 0xFF)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle int operations (16-bit)
	elif buffer_type_obj.name == "int":
	result = self.args.journal_write_int(journal_type, buffer_idx, int(value) & 0xFFFF)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle dint operations (32-bit)
	elif buffer_type_obj.name == "dint":
	result = self.args.journal_write_dint(journal_type, buffer_idx, int(value) & 0xFFFFFFFF)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle lint operations (64-bit)
	elif buffer_type_obj.name == "lint":
	result = self.args.journal_write_lint(journal_type, buffer_idx, int(value))
	# Handle byte operations (8-bit unsigned)
	elif buffer_type_obj.name == "byte":
	int_value = int(value)
	if int_value < 0 or int_value > 0xFF:
	raise OverflowError("Value out of range for 8-bit unsigned byte")
	result = self.args.journal_write_byte(journal_type, buffer_idx, int_value)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle int operations (16-bit signed)
	elif buffer_type_obj.name == "int":
	int_value = int(value)
	if int_value < -0x8000 or int_value > 0x7FFF:
	raise OverflowError("Value out of range for 16-bit signed int")
	result = self.args.journal_write_int(journal_type, buffer_idx, int_value)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle dint operations (32-bit signed)
	elif buffer_type_obj.name == "dint":
	int_value = int(value)
	if int_value < -0x80000000 or int_value > 0x7FFFFFFF:
	raise OverflowError("Value out of range for 32-bit signed dint")
	result = self.args.journal_write_dint(journal_type, buffer_idx, int_value)
	if result != 0:
	return False, f"Journal write failed with code {result}"
	return True, "Success"
	# Handle lint operations (64-bit signed)
	elif buffer_type_obj.name == "lint":
	int_value = int(value)
	if int_value < -0x8000000000000000 or int_value > 0x7FFFFFFFFFFFFFFF:
	raise OverflowError("Value out of range for 64-bit signed lint")
	result = self.args.journal_write_lint(journal_type, buffer_idx, int_value)