addDriver()

void fl::ChannelManager::addDriver	(	int	priority,
		fl::shared_ptr< IChannelDriver >	driver )

Add a driver with priority (higher priority = preferred)

Parameters

priority	Driver priority (higher values = higher priority)
driver	Shared driver implementation (allows caller to retain reference for testing)

Note

Platform-specific code calls this during static initialization

Drivers are automatically sorted by priority on each insertion

Driver name is obtained via driver->getName()

If driver->getName() returns empty string, driver is rejected (emits FL_WARN and returns)

If a driver with the same name already exists, it will be replaced:

1. FL_WARN emitted about replacement
2. All drivers polled until READY state (1 second timeout)
3. Old driver removed (shared_ptr may trigger deletion)
4. New driver added with specified priority

Definition at line 87 of file manager.cpp.hpp.

                                                                                {
    if (!driver) {
        FL_WARN("ChannelManager::addDriver() - Null driver provided");
        return;
    }
 
    // Get driver name from the driver itself
    fl::string engineName = driver->getName();
 
    // Reject drivers with empty names
    if (engineName.empty()) {
        FL_WARN("ChannelManager::addDriver() - Engine has empty name (driver->getName() returned empty string)");
        return;
    }
 
    // Check if driver with this name already exists
    bool replacing = false;
    for (const auto& entry : mDrivers) {
        if (entry.name == engineName) {
            // True-duplicate fast path: same shared_ptr at same priority is
            // a no-op (legacy clockless controllers may pre-bind the same
            // driver singleton from many template instantiations). Skip the
            // replace flow entirely so we don't waitForReady() or emit a
            // spurious "Replacing" warning.
            if (entry.driver == driver && entry.priority == priority) {
                FL_DBG("ChannelManager::addDriver() - '" << engineName.c_str()
                       << "' already registered at priority " << priority
                       << " (idempotent no-op)");
                return;
            }
            replacing = true;
            FL_WARN("ChannelManager::addDriver() - Replacing existing driver '" << engineName.c_str() << "'");
            break;
        }
    }
 
    // If replacing, wait for all drivers to become READY
    if (replacing) {
        FL_DBG("ChannelManager: Waiting for all drivers to become READY before replacement");
        waitForReady();
 
        // Remove the old driver with matching name (shared_ptr may trigger deletion)
        for (size_t i = 0; i < mDrivers.size(); ++i) {
            if (mDrivers[i].name == engineName) {
                FL_DBG("ChannelManager: Removing old driver '" << engineName.c_str() << "' (shared_ptr may delete)");
                if (mDrivers[i].driver) {
                    mDrivers[i].driver->setPollNeededCallback(IChannelDriver::PollNeededCallback());
                }
                mDrivers.erase(mDrivers.begin() + i);
                break;
            }
        }
    }
 
    // Respect exclusive driver mode: auto-disable if name doesn't match exclusive driver
    bool enabled = true;  // Default: enabled
    if (!mExclusiveDriver.empty()) {
        enabled = (engineName == mExclusiveDriver);  // Only enable if matches exclusive driver
    }
 
    mDrivers.push_back({priority, driver, engineName, enabled});
    driver->setPollNeededCallback(mPollNeededCallback);
 
    // Build capability string for debug output. Gate the entire block behind
    // FASTLED_HAS_DBG because the `capStr` exists ONLY to feed the FL_DBG
    // line below. On release builds (FASTLED_HAS_DBG=0 — i.e. the default
    // SKETCH_HAS_LARGE_MEMORY=0 path AND any -DFASTLED_LOG_VERBOSITY=0
    // opt-in build via the gating in fl/log/log.h) the FL_DBG itself is a
    // no-op, but without this guard the `fl::string capStr` allocation +
    // two `if` branches still emitted code. See #2773 item 2.3 follow-up.
#if FASTLED_HAS_DBG
    IChannelDriver::Capabilities caps = driver->getCapabilities();
    fl::string capStr;
    if (caps.supportsClockless) {
        capStr += "CLOCKLESS";
    }
    if (caps.supportsSpi) {
        if (!capStr.empty()) capStr += "|";
        capStr += "SPI";
    }
    if (capStr.empty()) {
        capStr = "NONE";
    }
 
    FL_DBG("ChannelManager: Added driver '" << engineName.c_str() << "' (priority " << priority << ", caps: " << capStr.c_str() << ")");
#endif
 
    // Sort drivers by priority descending (higher values first) after each insertion
    // Higher priority values = higher precedence (e.g., priority 50 selected over priority 10)
    // Only 1-4 drivers expected — sort_small skips the quicksort_impl
    // instantiation entirely (see #2907 for the bloat motivation).
    fl::sort_small(mDrivers.begin(), mDrivers.end());
}

References fl::basic_string::c_str(), fl::basic_string::empty(), FL_DBG, FL_WARN, mDrivers, mExclusiveDriver, mPollNeededCallback, fl::sort_small(), fl::IChannelDriver::Capabilities::supportsClockless, fl::IChannelDriver::Capabilities::supportsSpi, and waitForReady().

Referenced by setExclusiveDriver().

Here is the call graph for this function:

Here is the caller graph for this function: