Twinit Scenarios

twinitScenarios.md

Twinit Row-Key Request Scenarios

This document describes the four execution paths in twcrdsvc ProcessorImpl for handling GetTwRowKeysRequest, controlled by the breg flag bbit_twcrdsvc_enable_row_keys_calculations.

Request Flow Diagram

sequenceDiagram
    autonumber
    actor UI as UI or Caller
    participant twcrdsvc as twcrdsvc ProcessorImpl
    participant RM as RowManager in twcrdsvc
    participant twinitClient as TwinitClientWrapper
    participant twinit as twinit service

    UI->>twcrdsvc: GetTwRowKeysRequest

    Note over twcrdsvc: Mode selected by bbit_twcrdsvc_enable_row_keys_calculations
    Note over twcrdsvc: 0 = twinitOnly
    Note over twcrdsvc: 1 = diffWithTwinit
    Note over twcrdsvc: 2 = diffWithTwcrdsvc
    Note over twcrdsvc: other = twcrdsvcOnly

    alt Scenario A: twinitOnly (mode 0)
        twcrdsvc->>twinitClient: populateTwinitRowKeyResponse
        twinitClient->>twinit: GetRowKeyFromTwainRequest
        twinit-->>twinitClient: RowKeyResponse
        twinitClient-->>twcrdsvc: twinit row keys
        twcrdsvc-->>UI: Return twinit row keys
    else Scenario B: diffWithTwinit (mode 1)
        par In parallel
            twcrdsvc->>twinitClient: populateTwinitRowKeyResponse
            twinitClient->>twinit: GetRowKeyFromTwainRequest
            twinit-->>twinitClient: RowKeyResponse
            twinitClient-->>twcrdsvc: twinit row keys
        and
            twcrdsvc->>RM: createRowManager and loadRowKeys
            RM-->>twcrdsvc: computed row keys
        end
        twcrdsvc-->>UI: Return twinit row keys immediately
        twcrdsvc->>twcrdsvc: Async diff job twinit vs computed
    else Scenario C: diffWithTwcrdsvc (mode 2)
        par In parallel
            twcrdsvc->>twinitClient: populateTwinitRowKeyResponse
            twinitClient->>twinit: GetRowKeyFromTwainRequest
            twinit-->>twinitClient: RowKeyResponse
            twinitClient-->>twcrdsvc: twinit row keys
        and
            twcrdsvc->>RM: createRowManager and loadRowKeys
            RM-->>twcrdsvc: computed row keys
        end
        twcrdsvc-->>UI: Return computed row keys immediately
        twcrdsvc->>twcrdsvc: Async diff job twinit vs computed
    else Scenario D: twcrdsvcOnly (default fallback)
        twcrdsvc->>RM: createRowManager and loadRowKeys
        RM-->>twcrdsvc: computed row keys
        twcrdsvc-->>UI: Return computed row keys
    end

    Note over twinitClient,twinit: Twain path is exposed through twinit request handling
    Note over RM: Cash row typing and filters happen in twrowmanager flow

Loading

Scenario Descriptions

Scenario A: twinitOnly (mode = 0)

• Use case: Pass-through mode; use Twain as single source of truth
• Flow: Direct request to twinit → GetRowKeyFromTwainRequest → RowKeyResponse
• Response: Twinit row keys returned directly to caller
• Code path: s_twcrdsvc_processorimpl.cpp#L382

Scenario B: diffWithTwinit (mode = 1)

• Use case: Validation mode; compute rows in twcrdsvc but serve twinit first
• Flow:
  • Twinit request and RowManager computation run in parallel
  • Twinit row keys returned immediately to caller
  • Async diff job enqueued to compare row keys and log differences
• Response: Twinit row keys (fast path)
• Logging: Diff results logged asynchronously
• Code path: s_twcrdsvc_processorimpl.cpp#L383

Scenario C: diffWithTwcrdsvc (mode = 2)

• Use case: Migration mode; compute rows in twcrdsvc, serve them, but validate against twinit
• Flow:
  • Twinit request and RowManager computation run in parallel
  • Computed row keys returned immediately to caller
  • Async diff job enqueued to compare row keys and log differences
• Response: Computed row keys (fast path)
• Logging: Diff results logged asynchronously
• Code path: s_twcrdsvc_processorimpl.cpp#L407

Scenario D: twcrdsvcOnly (default)

• Use case: Full migration; use only twcrdsvc RowManager computation
• Flow: RowManager computes row keys
• Response: Computed row keys
• Twinit: Not called
• Code path: s_twcrdsvc_processorimpl.cpp#L449

Key Components

TwinitClientWrapper

• File: services/twcrdsvc/src/servicelib/s_twcrdsvc_twinitclientwrapper.cpp
• Method: populateTwinitRowKeyResponse()
• Responsibility: Encapsulates TCP communication with twinit service

RowManager

• Directory: services/twcrdsvc/twrowmanager/
• Key method: createRowManager() in s_twcrdsvc_rowmanagerutils.cpp
• Responsibility: Computes row keys using TPDB-based position retrieval and filtering logic

Cash Row Typing

• Row types: CASH_BALANCE (12) and NON_SECURITY_CASH (13)
• Definition: twrowmanager_rowmanagerutils.h#L35
• Formulas: twzColFormulas.cpp#L4516

Related JIRA

• ENG1SSTW-6655: Twain not painting extraneous data for new cash rows
• Fix: Updated settled-cash formulas to gate on both row types (CASH_BALANCE OR NON_SECURITY_CASH)
• Context: ENG1SSTW-6655_CONTEXT.md