Device Manager
=====================

The `libxdaq` function :cpp:func:`xdaq::get_device_manager` loads a :cpp:struct:`xdaq::DeviceManager` for managing XDAQ devices.
Two manager types, `ok` and `thor`, are available for interfacing with USB and Thunderbolt devices, respectively.

+---------------------+-------------------+
| Device Manager Name | Interface         |
+=====================+===================+
|  ok                 | Opal Kelly USB    |
+---------------------+-------------------+
|  thor               | Thunderbolt       |
+---------------------+-------------------+

The actual file name of the manager depends on the platform.

+----------------+-----------------------------------+
| Platform       | Device Manager Name               |
+================+===================================+
|  Windows       | **xxx** _device_manager.dll       |
+----------------+-----------------------------------+
|  macOS         | lib **xxx** _device_manager.dylib |
+----------------+-----------------------------------+
|  Linux         | lib **xxx** _device_manager.so    |
+----------------+-----------------------------------+


Example
-------
.. code-block:: cpp

    #include <xdaq/device_manager.h>
    #include <filesystem>
    #include <iostream>

    int main() {
        const std::filesystem::path manager_path{"libthor_device_manager.so"};
        try {
            auto manager = xdaq::get_device_manager(manager_path);
            std::cout << "Device Manager loaded successfully" << std::endl;
        } catch (const std::exception &e) {
            std::cerr << "Failed to load manager" << std::endl;
            std::cerr << e.what() << std::endl;
            return 1;
        }
        return 0;
    }

Manager Caching
---------------
:cpp:func:`xdaq::get_device_manager` caches loaded managers by their canonical file path.
Calling it again with the same library while a previous instance is still alive returns the
same shared instance instead of loading the library twice. The underlying shared library is
unloaded once the last reference to the manager is released.

Device Ownership
----------------
Devices created through a manager are protected by a cross-process ownership lock.
When a device is opened, an exclusive lock file is acquired under the system temporary
directory (``libxdaq_locks``). If another process already holds the lock,
:cpp:func:`xdaq::DeviceManager::create_device` fails with a "Device is already occupied" error.
The lock is derived from the manager's file name and the device configuration, so different
applications bundling their own copy of the same manager library still contend for the same
physical device.

Device Discovery
----------------
To enumerate devices across multiple managers without permanently claiming them, use the
device scanner (see :doc:`device_scanner`). It reports each device as available, occupied by
another process, or failed to query.