DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/Classes/Locking.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Classes/Locking/LockRecord.cs Common/DTS.CommonCore/Classes/Locking/LockError.cs	2026-04-16T02:40:09.269029+00:00	Qwen/Qwen3-Coder-Next-FP8	1	ee1fc4660f405448

Locking

Purpose

This module defines core data structures for representing and handling locking state and errors within the DTS system. Specifically, LockRecord encapsulates the metadata of an active lock (e.g., who holds it, when it was created, and what resource it pertains to), while LockError provides a structured way to represent lock-related error conditions—including recoverable states like lock theft or loss—enabling callers to programmatically respond to specific failure modes. Together, they serve as the foundational data models for a locking service, likely used in distributed or multi-user scenarios where resource contention must be managed.

---

Public Interface

LockRecord

A read-only data class representing the state of a lock.

• Constructor:

  public LockRecord(string user, string machine, DateTime createTime, DateTime lastUpdate, string itemKey, int itemCategory, int itemId)
  

  Initializes a new instance with the specified lock metadata. All properties are set once at construction and immutable thereafter.

• Properties:

  • string LockingUserName – The username of the entity holding the lock.
  • string LockingMachineName – The machine name of the entity holding the lock.
  • DateTime CreationTime – Timestamp when the lock was first acquired.
  • DateTime LastUpdated – Timestamp of the last lock maintenance (e.g., heartbeat or renewal).
  • string ItemKey – A string-based identifier for the locked item (e.g., a unique key or path).
  • int ItemCategory – An integer category code (corresponding to LockCategories in the database) classifying the type of item being locked.
  • int ItemId – A numeric identifier for the locked item (likely a primary key in a database table).

LockError

A read-only data class representing an error condition in lock operations.

• Constructor:

  public LockError(int error, string message, string user = null, string machine = null)
  

  Initializes a new instance with an error code, descriptive message, and optional context about the locking user/machine.

• Properties:

  • int ErrorCode – The numeric error code (read-only after construction).
  • string Message – Human-readable error description (read-only after construction).
  • string LockingUser – Username associated with the error (defaults to string.Empty if null).
  • string LockingMachine – Machine name associated with the error (defaults to string.Empty if null).
  • bool LockStolen – true if ErrorCode == LOCKSTOLEN_ERROR (i.e., 998).
  • bool LockLost – true if ErrorCode == LOCKDOESNTEXIST_ERROR (i.e., 997).

• Constants:

  • BAD_NETPATH_ERROR = 994 – Network path error (e.g., lost remote DB connection).
  • SEM_TIMEOUT_ERROR = 995 – Semaphore timeout (e.g., connection failure).
  • ITEM_NOT_FOUND = 996 – Referenced item does not exist.
  • LOCKDOESNTEXIST_ERROR = 997 – Lock record no longer exists (e.g., expired or deleted).
  • LOCKSTOLEN_ERROR = 998 – Lock was forcibly released by another party.
  • UNKNOWN_ERROR = 999 – Generic/unspecified error.

---

Invariants

• LockRecord instances are immutable after construction: all properties are readonly (via auto-properties with private set implied by lack of setters) and initialized only in the constructor.
• LockError.ErrorCode, Message, LockingUser, and LockingMachine are immutable after construction (via private set).
• LockingUser and LockingMachine in LockError are never null; if null is passed to the constructor, they default to string.Empty.
• LockStolen and LockLost are derived solely from ErrorCode and are guaranteed to be consistent with the defined constants.

---

Dependencies

• Internal dependencies:
  • System (for DateTime, string, object, etc.).
  • System.Data (imported but unused in these files; may indicate legacy or future use).
• External dependencies (inferred):
  • Likely consumed by other modules in DTS.CommonCore (e.g., a locking service or database persistence layer).
  • ItemCategory suggests integration with a database-defined LockCategories table (not present in source, but referenced in XML doc).
  • Error constants (994–999) imply coupling to SQL Server or ADO.NET error handling (per comments referencing SqlClient).

---

Gotchas

• System.Data import is unused: The using System.Data; statement in LockRecord.cs serves no purpose in the current implementation and may be legacy or placeholder.
• LockingUser/LockingMachine null-safety: While LockError constructor normalizes null inputs to string.Empty, callers must be aware that null is not preserved—this may mask missing context if not handled explicitly.
• No validation in constructor: Neither LockRecord nor LockError validates inputs (e.g., empty strings, negative ItemId/ItemCategory). Callers must ensure data integrity externally.
• LockLost vs. LockStolen semantics: The distinction between LOCKDOESNTEXIST_ERROR (LockLost) and LOCKSTOLEN_ERROR (LockStolen) is subtle:
  • LockLost implies the lock vanished without explicit release (e.g., timeout, crash).
  • LockStolen implies another party intentionally released the lock (e.g., admin override).
    This distinction may be critical for retry or conflict-resolution logic but is not enforced programmatically.
• No versioning or extensibility mechanism: The classes are simple DTOs with no support for forward/backward compatibility (e.g., new fields would require breaking changes).