Implementation of Multithreading in D365 F&O through X++

Before you reach for multithreading — check these first

Multithreading adds architectural complexity. Before implementing it, verify these simpler optimisations are already in place — they often resolve performance problems without parallelism:

If these are already optimised and the batch is still too slow — then multithreading is the right next step.

The three approaches to parallel batch processing

The Top Picking pattern — full implementation

The architecture has four components:

The staging table

Create a table named CSTVendStagingTable with at minimum these fields:

Component 1 — The DataContract class

/// <summary>
/// DataContract for the multithreading coordinator batch job.
/// Exposes the thread count parameter on the batch dialog.
/// </summary>
[DataContract]
public class CSTMultiThreadContract
{
    private int numberOfThreads;

    [DataMember,
     SysOperationLabel(literalStr("Number of parallel threads")),
     SysOperationHelpText(literalStr("Maximum is 16 — see batch server configuration."))]
    public int parmNumberOfThreads(int _numberOfThreads = numberOfThreads)
    {
        numberOfThreads = _numberOfThreads;
        return numberOfThreads;
    }
}

Component 2 — The coordinator Controller class

/// <summary>
/// SysOperationServiceController for the multithreading coordinator.
/// This is the class that has an Action Menu Item and that users schedule.
/// It is responsible ONLY for creating the worker tasks — it finishes in seconds.
/// </summary>
public class CSTMultiThreadController extends SysOperationServiceController
{
    protected void new()
    {
        // Points to the process() method on CSTMultiThreadService
        super(classStr(CSTMultiThreadService),
              methodStr(CSTMultiThreadService, process),
              SysOperationExecutionMode::Synchronous);
    }

    public ClassDescription defaultCaption()
    {
        return "Vendor Staging — Multithreaded Processor";
    }

    public static CSTMultiThreadController construct(
        SysOperationExecutionMode _executionMode = SysOperationExecutionMode::Synchronous)
    {
        CSTMultiThreadController controller = new CSTMultiThreadController();
        controller.parmExecutionMode(_executionMode);
        return controller;
    }

    public static void main(Args _args)
    {
        CSTMultiThreadController controller = CSTMultiThreadController::construct();
        controller.parmArgs(_args);
        controller.startOperation();
    }
}

Component 3 — The coordinator Service class

This is the most important class in the pattern. It does three things: moves records to InProcessing status (the snapshot), creates one worker task per requested thread, and saves all tasks to the batch header in a single operation.

/// <summary>
/// Service class for the coordinator batch job.
/// Responsible for:
///   1. Snapshotting records by setting them to InProcessing status
///   2. Spawning N worker tasks on the current batch header
/// This class finishes in seconds — all actual processing is done by the worker tasks.
/// </summary>
public class CSTMultiThreadService extends SysOperationServiceBase
{
    public void process(CSTMultiThreadContract _contract)
    {
        CSTVendStagingTable            stagingTable;
        SysOperationServiceController  workerController;
        BatchHeader                    batchHeader;
        int                             threadCount;
        int                             totalThreads = _contract.parmNumberOfThreads();
        RecordInsertList                logList;

        // Validate thread count — hard limit of 16 from Microsoft documentation
        if (totalThreads <= 0 || totalThreads > 16)
        {
            throw error("Number of threads must be between 1 and 16.");
        }

        // Step 1: Check whether any records are waiting to be processed
        select count(RecId) from stagingTable
            where stagingTable.ProcessingStatus == CSTProcessingStatus::ToBeProcessed;

        if (stagingTable.RecId == 0)
        {
            info("No records in ToBeProcessed status. Nothing to do.");
            return;
        }

        // Step 2: Snapshot — move all ToBeProcessed records to InProcessing
        // This prevents new records arriving mid-run from causing thread imbalance
        update_recordset stagingTable
            setting ProcessingStatus = CSTProcessingStatus::InProcessing
            where stagingTable.ProcessingStatus == CSTProcessingStatus::ToBeProcessed;

        info(strFmt("%1 records moved to InProcessing status.", stagingTable.RecId));

        // Step 3: Get the current batch header to add tasks to
        // getCurrentBatchHeader() returns the BatchHeader of the currently running batch job
        // This ensures worker tasks are children of THIS job — not independent jobs
        batchHeader = this.getCurrentBatchHeader();

        if (!batchHeader)
        {
            // Fallback: if running interactively (not as a batch), create a new header
            batchHeader = BatchHeader::construct();
        }

        // Step 4: Create one worker controller per requested thread
        for (threadCount = 1; threadCount <= totalThreads; threadCount++)
        {
            workerController = CSTWorkerController::construct();
            workerController.parmDialogCaption(
                strFmt("Vendor Staging Worker — Thread %1 of %2", threadCount, totalThreads));

            batchHeader.addTask(workerController);
        }

        // Step 5: Save all tasks at once
        batchHeader.save();

        info(strFmt("%1 worker tasks created and queued.", totalThreads));
    }
}

Component 4a — The worker Controller class

/// <summary>
/// SysOperationServiceController for the worker tasks.
/// This class does NOT have a menu item — it is only instantiated
/// programmatically by CSTMultiThreadService.
/// </summary>
public class CSTWorkerController extends SysOperationServiceController
{
    protected void new()
    {
        super(classStr(CSTWorkerService),
              methodStr(CSTWorkerService, process),
              SysOperationExecutionMode::Synchronous);
    }

    public ClassDescription defaultCaption()
    {
        return "Vendor Staging Worker";
    }

    public static CSTWorkerController construct(
        SysOperationExecutionMode _executionMode = SysOperationExecutionMode::Synchronous)
    {
        CSTWorkerController controller = new CSTWorkerController();
        controller.parmExecutionMode(_executionMode);
        return controller;
    }

    public static void main(Args _args)
    {
        CSTWorkerController controller = CSTWorkerController::construct();
        controller.parmArgs(_args);
        controller.startOperation();
    }
}

Component 4b — The worker Service class

This is the heart of the Top Picking pattern. The combination of readPast(true), pessimisticlock, and firstOnly is what makes parallel processing safe.

/// <summary>
/// Service class for each worker task.
/// Uses pessimistic locking with readPast to implement Top Picking:
///   - pessimisticlock: locks the selected record so no other thread can select it
///   - readPast(true): skips records that are locked by other threads
/// This combination guarantees each record is processed by exactly one thread.
/// </summary>
public class CSTWorkerService extends SysOperationServiceBase
{
    public void process()
    {
        CSTVendStagingTable stagingTable;

        // readPast(true) is the critical call that enables Top Picking.
        // When true: if this thread tries to select a record that is locked
        // by another thread, it skips that record and moves to the next one.
        // Without this, the thread would wait (block) until the lock is released,
        // causing all threads to queue up behind the same records.
        stagingTable.readPast(true);

        do
        {
            try
            {
                ttsBegin;

                // pessimisticlock: locks the selected record at the database level.
                // firstOnly: gets exactly one record.
                // Together: this thread claims one record that no other thread can claim.
                select pessimisticlock firstOnly stagingTable
                    where stagingTable.ProcessingStatus == CSTProcessingStatus::InProcessing;

                if (stagingTable)
                {
                    // Process the claimed record
                    CSTWorkItemProcessor::processRecord(stagingTable);

                    // Mark as processed within the same transaction as the lock
                    stagingTable.ProcessingStatus   = CSTProcessingStatus::Processed;
                    stagingTable.ProcessedDateTime  = DateTimeUtil::utcNow();
                    stagingTable.update();
                }

                ttsCommit;
                // Lock is released on ttsCommit — other threads can now access
                // the next InProcessing records
            }
            catch (Exception::Deadlock)
            {
                // SQL Server deadlock — safe to retry immediately
                // The transaction is automatically rolled back on deadlock
                ttsAbort;
                retry;
            }
            catch (Exception::UpdateConflict)
            {
                // Optimistic concurrency conflict — retry
                ttsAbort;
                if (appl.ttsLevel() == 0)
                {
                    retry;
                }
                else
                {
                    throw Exception::UpdateConflict;
                }
            }
            catch (Exception::Error)
            {
                // Business logic error on this specific record
                // Do NOT re-throw — mark the record as Error and continue
                // to the next record so one bad record does not kill the thread
                ttsAbort;

                // Re-select for update outside the failed transaction
                CSTVendStagingTable errorRecord;
                select forUpdate firstOnly errorRecord
                    where errorRecord.RecId == stagingTable.RecId;

                if (errorRecord)
                {
                    ttsBegin;
                    errorRecord.ProcessingStatus = CSTProcessingStatus::Error;
                    errorRecord.ErrorMessage     = infolog.text();
                    errorRecord.update();
                    ttsCommit;
                }
            }
        }
        while (stagingTable.RecId != 0); // Loop until no InProcessing records remain
    }
}

Component 5 — The work item processor

Separating the actual business logic into its own class is not just good practice — it enforces that each work item is truly autonomous. If your logic cannot fit cleanly into a standalone static method called with a single table buffer, that is a signal that your work item definition is too large or too dependent on other records.

/// <summary>
/// Processes a single record from CSTVendStagingTable.
/// This class is intentionally NOT a SysOperation class — it is a pure
/// business logic class called by CSTWorkerService.
/// Keep all logic for one work item here — autonomous and self-contained.
/// </summary>
public class CSTWorkItemProcessor
{
    public static void processRecord(CSTVendStagingTable _stagingRecord)
    {
        VendTable   vendTable;
        VendTrans   vendTrans;

        // Validate the vendor exists before processing
        vendTable = VendTable::find(_stagingRecord.VendAccount);

        if (!vendTable)
        {
            throw error(strFmt("Vendor %1 not found. Record %2 cannot be processed.",
                _stagingRecord.VendAccount, _stagingRecord.RecId));
        }

        // Your actual business logic goes here
        // This example creates a vendor transaction record from staging data
        // In a real implementation this would be your order creation,
        // data validation, GL posting, or whatever the batch job is doing

        ttsBegin;

        vendTrans.AccountNum    = _stagingRecord.VendAccount;
        vendTrans.TransDate     = today();
        vendTrans.AmountMST     = _stagingRecord.InvoiceAmount;
        vendTrans.TransType     = LedgerTransType::Purch;
        // ... set other required fields
        vendTrans.insert();

        ttsCommit;
    }
}

How pessimisticlock and readPast work together

This is the mechanism that prevents duplicate processing. Understanding it at the database level explains why the pattern works and what happens when it is implemented incorrectly.

The SQL translation is exact: pessimisticlock in X++ generates WITH (UPDLOCK) in the SQL query. readPast(true) adds READPAST to the hint. The combination — WITH (UPDLOCK, READPAST) — is the standard SQL Server pattern for queue processing: lock what you claim, skip what others have claimed.

Configuring the batch server for maximum threads

Creating 8 worker tasks in code does not guarantee 8 tasks run simultaneously. The batch server has a configurable maximum thread limit.

1. Navigate to System Administration → Setup → Server Configuration
2. Find the AOS instance that runs your batch jobs
3. Set Maximum batch threads — Microsoft's documented maximum is 16
4. Save and restart the batch service if required

Verifying your threads are genuinely running in parallel

After running the coordinator job, navigate to System Administration → Inquiries → Batch jobs. Find the coordinator job by its description. Click the Job ID link to drill into the tasks.

You should see N tasks — one per thread you specified — all showing status Executing simultaneously. When processing is complete they will all move to Ended.

Performance verification calculation is mentioned below : - 

Complete class list for your Visual Studio project