0930-appendix-c-libswsscommon-api-usage-in-cpp.md

16. Appendix C — libswsscommon API Usage Guide (C++)

This appendix provides a summary of the libswsscommon API usage guide.

16.1 Overview of libswsscommon

libswsscommon is SONiC’s C++ helper library that wraps:

• Redis client operations
• Notification channels
• Table abstractions
• Producer/consumer semantics
• Event loops (Select interface)

The library is used by:

• orchagent
• vlanmgrd, intfmgrd, teammgrd
• neighsyncd, portsyncd
• fdbsyncd
• Various platform daemons

16.2 DBConnector

Lowest-level Redis connector in SONiC.

Example: Connecting to APPL_DB

#include "dbconnector.h"
using namespace swss;

DBConnector appl_db("APPL_DB", 0);  // 0 = timeout in ms

Parameters:

• "APPL_DB" — database name
• 0 — timeout (0 = no timeout)

DBConnector is passed into all other objects.

---

16.3 Table — Direct Hash Access

Use Table when:

• reading CONFIG_DB
• reading STATE_DB
• reading static APPL_DB entries
• writing without notification semantics

Example: Read a PORT row

DBConnector db("CONFIG_DB", 0);
Table portTable(&db, "PORT");

std::vector<FieldValueTuple> fvs;
portTable.get("Ethernet0", fvs);

for (auto &fv : fvs)
{
    std::cout << fvField(fv) << "=" << fvValue(fv) << std::endl;
}

Example: Write to a hash directly

FieldValueTuple fv1("admin_status", "up");
FieldValueTuple fv2("mtu", "9216");
std::vector<FieldValueTuple> fvs = {fv1, fv2};

portTable.set("Ethernet0", fvs);

Example: Delete a row

portTable.del("Ethernet0");

16.4 ProducerStateTable — Write With Notification

Used heavily when a daemon wants to:

• send desired state to orchagent
• notify orchagent of configuration changes

Example: Add VLAN Member

DBConnector db("APPL_DB", 0);
ProducerStateTable tbl(&db, "VLAN_MEMBER_TABLE");

FieldValueTuple fv("tagging_mode", "untagged");
std::vector<FieldValueTuple> fvs = {fv};

tbl.set("Vlan10|Ethernet0", fvs);

Example: Delete an entry

tbl.del("Vlan10|Ethernet0");

ProducerStateTable ensures:

• value is written to Redis
• event is queued atomically
• orchagent receives update in-order

16.5 ConsumerStateTable — Event-Driven Reads

Used by:

• orchagent (reading APPL_DB)
• neighsyncd (reading kernel → APPL_DB writes)
• teammgrd, vlanmgrd, intfmgrd

Basic Example

DBConnector db("APPL_DB", 0);
ConsumerStateTable cst(&db, "PORT_TABLE");

std::string key;
std::vector<FieldValueTuple> fvs;

if (cst.pop(key, fvs))
{
    // process event for key
}

---

16.6 Select — Event Multiplexer

Select allows SONiC daemons to listen to multiple tables.

Multi-Table Example

DBConnector db("APPL_DB", 0);

ConsumerStateTable portT(&db, "PORT_TABLE");
ConsumerStateTable vlanT(&db, "VLAN_TABLE");
ConsumerStateTable fdbT(&db, "FDB_TABLE");

Select selector;
selector.addSelectable(&portT);
selector.addSelectable(&vlanT);
selector.addSelectable(&fdbT);

while (true)
{
    Selectable *sel;
    int result = selector.select(&sel);

    if (result == Select::ERROR)
        continue;

    std::string key;
    std::vector<FieldValueTuple> fvs;

    if (sel == &portT)
    {
        portT.pop(key, fvs);
        // handle port event
    }
    else if (sel == &vlanT)
    {
        vlanT.pop(key, fvs);
        // handle VLAN event
    }
    else if (sel == &fdbT)
    {
        fdbT.pop(key, fvs);
        // handle FDB event
    }
}

This pattern guarantees:

• no busy waiting
• fair scheduling
• deterministic in-table ordering

16.7 Common SONiC Patterns

16.7.1 Pattern: CONFIG_DB → daemon → Linux + APPL_DB

• Use Table to read CONFIG_DB
• Use Linux syscalls (netlink) for system configuration
• Use ProducerStateTable to signal orchagent

16.7.2 Pattern: ASIC Event → syncd → daemon → APPL_DB

• syncd receives event
• writes to APPL_DB via ProducerStateTable
• orchagent processes event

16.7.3 Pattern: Reconciliation at Restart

Tables read via:

• Table.get()
• full table iteration via getTableKeys()

16.8 Best Practices

• Always prefer ProducerStateTable for APPL_DB writes
• Use Table for CONFIG_DB/STATE_DB
• Use Select for multi-table event loops
• Never block inside the event loop
• Keep FieldValuePairs minimal
• Always validate keys before writing

16.9 Summary

libswsscommon provides the glue that allows SONiC daemons to:

• read config
• publish desired state
• subscribe to updates
• receive event-driven notifications
• interact cleanly with orchagent

It is the foundation for building new SONiC daemons and extending existing ones.