Class program

| Home | Libraries | People | FAQ | More

## Class program

boost::compute::program — A compute program.

## Synopsis

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

    class program {
    public:
      // construct/copy/destruct
      program();
      explicit program(cl_program, bool = true);
      program(const program &);
      program(program &&) noexcept;
      program & operator=(const program &);
      program & operator=(program &&) noexcept;
      ~program();

      // public member functions
      cl_program & get() const;
      std::string source() const;
      std::vector< unsigned char > binary() const;
      std::vector< device > get_devices() const;
      context get_context() const;
      template<typename T> T get_info(cl_program_info) const;
      template<int Enum> unspecified get_info() const;
      template<typename T>
        T get_build_info(cl_program_build_info, const device &) const;
      void build(const std::string & = std::string());
      void compile(const std::string & = std::string());
      std::string build_log() const;
      kernel create_kernel(const std::string &) const;
      bool operator==(const program &) const;
      bool operator!=(const program &) const;

      // public static functions
      static program
      link(const std::vector< program > &, const context &,
           const std::string & = std::string());
      static program create_with_source(const std::string &, const context &);
      static program
      create_with_source(const std::vector< std::string > &, const context &);
      static program create_with_source_file(const std::string &, const context &);
      static program
      create_with_binary(const unsigned char *, size_t, const context &);
      static program
      create_with_binary(const std::vector< unsigned char > &, const context &);
      static program create_with_binary_file(const std::string &, const context &);
      static program
      create_with_builtin_kernels(const context &, const std::vector< device > &,
                                  const std::string &);
      static program
      build_with_source(const std::string &, const context &,
                        const std::string & = std::string());
    };

## Description

The program class represents an OpenCL program.

Program objects are created with one of the static `create_with_*` functions. For example, to create a program from a source string:

    std::string source = "__kernel void foo(__global int *data) { }";

    boost::compute::program foo_program =
        boost::compute::program::create_with_source(source, context);

And to create a program from a source file:

    boost::compute::program bar_program =
        boost::compute::program::create_with_source_file("/path/to/bar.cl", context);

Once a program object has been succesfully created, it can be compiled using the `build()` method:

    // build the program
    foo_program.build();

Once the program is built, kernel objects can be created using the `create_kernel()` method by passing their name:

    // create a kernel from the compiled program
    boost::compute::kernel foo_kernel = foo_program.create_kernel("foo");

See Also:

kernel

### `program` public construct/copy/destruct

1.     program();

   Creates a null program object.

2.     explicit program(cl_program program, bool retain = true);

   Creates a program object for `program`. If `retain` is `true`, the reference count for `program` will be incremented.

3.     program(const program & other);

   Creates a new program object as a copy of `other`.

4.     program(program && other) noexcept;

   Move-constructs a new program object from `other`.

5.     program & operator=(const program & other);

   Copies the program object from `other` to `*this`.

6.     program & operator=(program && other) noexcept;

   Move-assigns the program from `other` to `*this`.

7.     ~program();

   Destroys the program object.

### `program` public member functions

1.     cl_program & get() const;

   Returns the underlying OpenCL program.

2.     std::string source() const;

   Returns the source code for the program.

3.     std::vector< unsigned char > binary() const;

   Returns the binary for the program.

4.     std::vector< device > get_devices() const;

5.     context get_context() const;

   Returns the context for the program.

6.     template<typename T> T get_info(cl_program_info info) const;

   Returns information about the program.

   See the documentation for clGetProgramInfo() for more information.

7.     template<int Enum> unspecified get_info() const;

   This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

8.     template<typename T>
         T get_build_info(cl_program_build_info info, const device & device) const;

   Returns build information about the program.

   For example, this function can be used to retreive the options used to build the program:

       std::string build_options =
           program.get_build_info<std::string>(CL_PROGRAM_BUILD_OPTIONS);

   See the documentation for clGetProgramInfo() for more information.

9.     void build(const std::string & options = std::string());

   Builds the program with `options`.

   If the program fails to compile, this function will throw an `opencl_error` exception.

       try {
           // attempt to compile to program
           program.build();
       }
       catch(boost::compute::opencl_error &e){
           // program failed to compile, print out the build log
           std::cout << program.build_log() << std::endl;
       }

   See the documentation for clBuildProgram() for more information.

10.     void compile(const std::string & options = std::string());

    Compiles the program with `options`.

    | Warning
    This method is only available if the OpenCL version is 1.2 or later.

    See the documentation for clCompileProgram() for more information.

11.     std::string build_log() const;

    Returns the build log.

12.     kernel create_kernel(const std::string & name) const;

    Creates and returns a new kernel object for `name`.

    For example, to create the `"foo"` kernel (after the program has been created and built):

        boost::compute::kernel foo_kernel = foo_program.create_kernel("foo");

13.     bool operator==(const program & other) const;

    Returns `true` if the program is the same at `other`.

14.     bool operator!=(const program & other) const;

    Returns `true` if the program is different from `other`.

### `program` public static functions

1.     static program
       link(const std::vector< program > & programs, const context & context,
            const std::string & options = std::string());

   Links the programs in `programs` with `options` in `context`.

   | Warning
   This method is only available if the OpenCL version is 1.2 or later.

   See the documentation for clLinkProgram() for more information.

2.     static program
       create_with_source(const std::string & source, const context & context);

   Creates a new program with `source` in `context`.

   See the documentation for clCreateProgramWithSource() for more information.

3.     static program
       create_with_source(const std::vector< std::string > & sources,
                          const context & context);

   Creates a new program with `sources` in `context`.

   See the documentation for clCreateProgramWithSource() for more information.

4.     static program
       create_with_source_file(const std::string & file, const context & context);

   Creates a new program with `file` in `context`.

   See the documentation for clCreateProgramWithSource() for more information.

5.     static program
       create_with_binary(const unsigned char * binary, size_t binary_size,
                          const context & context);

   Creates a new program with `binary` of `binary_size` in `context`.

   See the documentation for clCreateProgramWithBinary() for more information.

6.     static program
       create_with_binary(const std::vector< unsigned char > & binary,
                          const context & context);

   Creates a new program with `binary` in `context`.

   See the documentation for clCreateProgramWithBinary() for more information.

7.     static program
       create_with_binary_file(const std::string & file, const context & context);

   Creates a new program with `file` in `context`.

   See the documentation for clCreateProgramWithBinary() for more information.

8.     static program
       create_with_builtin_kernels(const context & context,
                                   const std::vector< device > & devices,
                                   const std::string & kernel_names);

   Creates a new program with the built-in kernels listed in `kernel_names` for `devices` in `context`.

   | Warning
   This method is only available if the OpenCL version is 1.2 or later.

   See the documentation for clCreateProgramWithBuiltInKernels() for more information.

9.     static program
       build_with_source(const std::string & source, const context & context,
                         const std::string & options = std::string());

   Create a new program with `source` in `context` and builds it with `options`.

   In case BOOST_COMPUTE_USE_OFFLINE_CACHE macro is defined, the compiled binary is stored for reuse in the offline cache located in $HOME/.boost_compute on UNIX-like systems and in APPDATA%/boost_compute on Windows.