| Home | Libraries | People | FAQ | More

## Class system

boost::compute::system — Provides access to platforms and devices on the system.

## Synopsis

    // In header: <boost/compute/system.hpp>

    class system {
    public:

      // public static functions
      static device default_device();
      static device find_device(const std::string &);
      static std::vector< device > devices();
      static size_t device_count();
      static context default_context();
      static command_queue &
      default_queue(const command_queue & = command_queue());
      static void finish();
      static std::vector< platform > platforms();
      static size_t platform_count();
    };

## Description

The system class contains a set of static functions which provide access to the OpenCL platforms and compute devices on the host system.

The default_device() convenience method automatically selects and returns the "best" compute device for the system following a set of heuristics and environment variables. This simplifies setup of the OpenCL enviornment.

See Also: platform, device, context

### `system` public static functions

1.     static device default_device();

   Returns the default compute device for the system.

   The default device is selected based on a set of heuristics and can be influenced using one of the following environment variables:

   - `BOOST_COMPUTE_DEFAULT_DEVICE` - name of the compute device (e.g. "GTX TITAN")

   - `BOOST_COMPUTE_DEFAULT_DEVICE_TYPE` type of the compute device (e.g. "GPU" or "CPU")

   - `BOOST_COMPUTE_DEFAULT_PLATFORM` - name of the platform (e.g. "NVIDIA CUDA")

   - `BOOST_COMPUTE_DEFAULT_VENDOR` - name of the device vendor (e.g. "NVIDIA")

   - `BOOST_COMPUTE_DEFAULT_ENFORCE` - If this is set to "1", then throw a no_device_found() exception if any of the above environment variables is set, but a matching device was not found.

   The default device is determined once on the first time this function is called. Calling this function multiple times will always result in the same device being returned.

   If no OpenCL device is found on the system, a no_device_found exception is thrown.

   For example, to print the name of the default compute device on the system:

       // get the default compute device
       boost::compute::device device = boost::compute::system::default_device();

       // print the name of the device
       std::cout << "default device: " << device.name() << std::endl;

2.     static device find_device(const std::string & name);

   Returns the device with `name`.

   Throws: | no_device_found if no device with `name` is found.

3.     static std::vector< device > devices();

   Returns a vector containing all of the compute devices on the system.

   For example, to print out the name of each OpenCL-capable device available on the system:

       for(const auto &device : boost::compute::system::devices()){
           std::cout << device.name() << std::endl;
       }

4.     static size_t device_count();

   Returns the number of compute devices on the system.

5.     static context default_context();

   Returns the default context for the system.

   The default context is created for the default device on the system (as returned by default_device()).

   The default context is created once on the first time this function is called. Calling this function multiple times will always result in the same context object being returned.

6.     static command_queue &
       default_queue(const command_queue & user_queue = command_queue());

   Returns the default command queue for the system.

   If user-provided command queue is given, the system-wide default context and default device will be set up appropriately so that the default queue matches the default context and device.

   If the OpenCL context and device associated with user-provided command queue does not match the default context and device that have already been set, a set_default_queue_error exception is thrown. For example:

   The default queue is created once on the first time this function is called. Calling this function multiple times will always result in the same command queue object being returned.

7.     static void finish();

   Blocks until all outstanding computations on the default command queue are complete.

   This is equivalent to:

       system::default_queue().finish();

8.     static std::vector< platform > platforms();

   Returns a vector containing each of the OpenCL platforms on the system.

   For example, to print out the name of each OpenCL platform present on the system:

       for(const auto &platform : boost::compute::system::platforms()){
           std::cout << platform.name() << std::endl;
       }

9.     static size_t platform_count();

   Returns the number of compute platforms on the system.