uncomplicate.clojurecl.internal.utils

Utility functions used as helpers in other ClojureCL namespaces.
The user of the ClojureCL library would probably not need to use
any of the functions defined here.

error

(error err-code details)(error err-code)
Converts an OpenCL error code to an [ExceptionInfo]
(http://clojuredocs.org/clojure.core/ex-info)
with richer, user-friendly information.

Accepts a long `err-code` that should be one of the codes defined in
OpenCL standard, and an optional `details` argument that could be
anything that you think is informative.

See the available codes in the source of [[constants/dec-error]].
Also see the discussion about
[OpenCL error codes](http://streamcomputing.eu/blog/2013-04-28/opencl-1-2-error-codes/).

Examples:

    (error 0) => an ExceptionInfo instance
    (error -5 {:comment "Why here?""}) => an ExceptionInfo instance

maybe

macro

(maybe form)
Evaluates form in try/catch block; if an OpenCL-related exception is caught,
substitutes the result with the [ExceptionInfo](http://clojuredocs.org/clojure.core/ex-info)
object.
Non-OpenCL exceptions are rethrown. Useful when we do not want to let a minor
OpenCL error due to a driver incompatibility with the standard
or an unimplemented feature in the actual driver crash the application.
An [ExceptionInfo](http://clojuredocs.org/clojure.core/ex-info) object will be
put in the place of the expected result.

with-check

macro

(with-check status form)(with-check status details form)
Evaluates `form` if `status` is not zero (`CL_SUCCESS`), otherwise throws
an appropriate `ExceptionInfo` with decoded informative details.
It helps fith JOCL methods that return error codes directly, while
returning computation results through side-effects in arguments.

Example:

    (with-check (some-jocl-call-that-returns-error-code) result)

with-check-arr

macro

(with-check-arr status form)(with-check-arr status details form)
Evaluates `form` if the integer in the `status` primitive int array is `0`,
Otherwise throws an exception corresponding to the error code.
Similar to [[with-check]], but with the error code being held in an array instead
of being a primitive number. It helps with JOCL methods that return results
directly, and signal errors through side-effects in a primitive array argument.

    (let [err (int-array 1)
          res (some-jocl-call err)]
       (with-checl-arr err res))