| Home | Libraries | People | FAQ | More

## Class program

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

## Synopsis

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

    class program {
    public:

      // public member functions
      program();
      explicit program(cl_program, bool = true);
      program(const program &);
      program & operator=(const program &);
      program(program &&) noexcept;
      program & operator=(program &&) noexcept;
      ~program();
      cl_program & get() const;
      std::string source() const;
      std::vector< unsigned char > binary() const;
      std::vector< unsigned char > il_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(),
                   const std::vector< std::pair< std::string, program > > & = std::vector< std::pair< std::string, program > >());
      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_source_file(const std::vector< 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 create_with_il(const void *, const size_t, const context &);
      static program
      create_with_il(const std::vector< unsigned char > &, const context &);
      static program create_with_il_file(const std::string &, const context &);
      static program
      build_with_source(const std::string &, const context &,
                        const std::string & = std::string());
      static program
      build_with_source_file(const std::string &, const context &,
                             const std::string & = std::string());

      // private static functions
      static std::string read_source_file(const 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:

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 successfully 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 member functions

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 & operator=(const program & other);

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

5.     program(program && other) noexcept;

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

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

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

7.     ~program();

   Destroys the program object.

8.     cl_program & get() const;

   Returns the underlying OpenCL program.

9.     std::string source() const;

   Returns the source code for the program.

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

    Returns the binary for the program.

11.     std::vector< unsigned char > il_binary() const;

    Returns the SPIR-V binary for the program.

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

13.     context get_context() const;

    Returns the context for the program.

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

    Returns information about the program.

    See the documentation for

15.     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.

16.     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

17.     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

18.     void compile(const std::string & options = std::string(),
                     const std::vector< std::pair< std::string, program > > & headers = std::vector< std::pair< std::string, program > >());

    Compiles the program with `options`.

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

    See the documentation for

19.     std::string build_log() const;

    Returns the build log.

20.     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");

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

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

22.     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

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

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

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

5.     static program
       create_with_source_file(const std::vector< std::string > & files,
                               const context & context);

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

   See the documentation for

6.     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

7.     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

8.     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

9.     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

10.     static program
        create_with_il(const void * il_binary, const size_t il_size,
                       const context & context);

    Creates a new program with `il_binary` (SPIR-V binary) of `il_size` size in `context`.

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

    See the documentation for

11.     static program
        create_with_il(const std::vector< unsigned char > & il_binary,
                       const context & context);

    Creates a new program with `il_binary` (SPIR-V binary) in `context`.

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

    See the documentation for

12.     static program
        create_with_il_file(const std::string & file, const context & context);

    Creates a new program in `context` using SPIR-V binary `file`.

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

    See the documentation for

13.     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.

14.     static program
        build_with_source_file(const std::string & file, const context & context,
                               const std::string & options = std::string());

    Create a new program with `file` 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.

### `program` private static functions

1.     static std::string read_source_file(const std::string & file);