Svc::DpWriter (Active Component)

1. Introduction

Svc::DpWriter is an active component for writing data products to disk. It does the following:

1. Receive buffers containing filled data product containers. The buffers typically come from one or more components that produce data products. They typically pass through an instance of Svc::DpManager, and possibly through an instance of Svc::BufferAccumulator, before reaching DpWriter.

2. For each buffer B received in step 1:

   1. Perform any requested processing, such as data compression, on B.

   2. Write B to disk.

   3. If a notification port is connected, then send out a notification that the write occurred. An instance of Svc::DpCatalog can receive this notification and use it to update the data product catalog.

2. Requirements

3. Design

3.1. Component Diagram

The diagram below shows the DpWriter component.

3.2. Ports

DpWriter has the following ports:

3.3. State

DpWriter maintains the following state:

1. numDataProducts (U32): The number of data products written.

2. numBytes (U64): The number of bytes written.

3.4. Compile-Time Setup

1. The configuration constant DpWriterNumProcPorts specifies the number of ports for connecting components that perform processing.

2. The configuration DP_FILENAME_FORMAT specifies the file name format.

3.5. Runtime Setup

You can call the configure function to supply the DP file name prefix. This is the prefix used when constructing names of files to write. For more information about the file name format, see the File Format section.

If you do not call the configure function, then the default DP file name prefix is the empty string.

3.6. Port Handlers

3.6.1. schedIn

This handler sends out the state variables as telemetry.

3.6.2. bufferSendIn

This handler receives a mutable reference to a buffer B. It does the following:

1. Check that B is valid. If not, emit a warning event.

2. If the previous step succeeded, then check that the size of B is large enough to hold a data product container packet. If not, emit a warning event.

3. If the previous steps succeeded, then check that the packet header of B can be successfully deserialized. If not, emit a warning event.

4. If the previous steps succeeded, then check that the header hash of B is valid. If not, emit a warning event.

5. If the previous steps succeeded, then check that the data size recorded in the packet header fits within the buffer. If not, emit a warning event.

6. If the previous steps succeeded, then

   1. Read the ProcType field out of the container header stored in the memory pointed to by B. Let the resulting bit mask be M.

   2. Visit the port numbers of procBufferSendOut in order. For each port number N, if N is set in M, then invoke procBufferSendOut at port number N, passing in B. This step updates the memory pointed to by B in place.

   3. Write B to a file, using the format described in the File Format section. For the time stamp, use the time provided by timeGetOut.

7. If the file write succeeded and dpWrittenOut is connected, then send the file name, priority, and file size out on dpWrittenOut.

8. If B is valid, then send B on deallocBufferSendOut.

<a name="file_format"></a>

4. File Format

4.1. Data Format

Each file stores a serialized data product record, with the format described in the data products documentation.

4.2. File Name

The name of each file is formatted with the configurable format string DP_FILENAME_FORMAT. The format string must contain format specifications for the following arguments, in order.

The exact meaning of the DP file name prefix depends on the format string. Typically it is a directory path prefix.

<a name="ground_interface"></a>

5. Ground Interface

5.1. Commands

5.2. Telemetry

5.3. Events

6. Example Uses

<a name="top-diagrams"></a>

6.1. Topology Diagrams

The following topology diagram shows how to connect Svc::DpWriter to a DpManager component and a processor component. The diagrams use the following instances:

• dpManager: An instance of Svc::DpManager.

• dpProcessor: A component that processes data product containers.

• dpWriter: An instance of Svc::DpWriter.

• producer: A component that produces data products.

6.2. Sequence Diagrams

The following diagram shows what happens when a buffer is sent to DpWriter, is processed, and is written to disk.

sequenceDiagram
    activate producer
    activate dpManager
    activate dpWriter
    producer-)dpManager: Send buffer
    dpManager-)dpWriter: Send buffer [bufferSendIn]
    dpWriter->>dpProcessor: Process buffer B [procBufferSendOut]
    dpProcessor-->>dpWriter: Return
    dpWriter->>dpWriter: Write B to disk
    dpWriter->>bufferManager: Deallocate B [deallocBufferSendOut]
    bufferManager-->>dpWriter: Return
    deactivate dpWriter
    deactivate dpManager
    deactivate producer