Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

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] 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] 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] 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] 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] 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] 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);

PrevUpHomeNext