node-opencl-ts
Advanced tools
This is a fork of mikeseven's node-opencl project from: https://github.com/mikeseven/node-opencl (by https://github.com/mikeseven)
I've taken the initiative to renovate the existing code for my own purposes and now I'm sharing the result in hope that it will be useful for anyone else who is lacking typescript support with node-opencl.
This project contains full typings coverage of OpenCL 1.0-2.0 (and OpenCL 2.1, 2.2 ready to be implemented) specification (based on Khronos specification) with node-opencl specifics taken into account. The package also contains couple of minor bugfixes suggested by community PRs in original repo and couple of mine aesthetic interface changes / additions and changes related to management of deprecated OpenCL apis (basically I enabled the use of deprecated APIs if they were still supported by OpenCL implementation). Which I think may block mikeseven from merging current changes into node-opencl. Nevertheless in order to not partition the community with redundant library versions I'm open to kill this repo in event of merge with node-opencl.
One more thing, the typings are handcrafted, I've attempted to make the typings as verbose and type-safe as possible, this means that there is still room for improvement for both typings and the OpenCL bindings implementation itself (I'm open for both issues and PRs).
Currently there are just couple of v1.0-v2.0 functions that are not implemented (most of them are deprecated in OpenCL 1.2 - 2.0 or not needed at all due to the way node-opencl was implemented). OpenCL v2.1 and v2.2 are not implemented at all so again issues and PRs are welcome.
And the last thing I wanted to mention. Due to hardware nature of OpenCL segfaults, BSODs, freezes and computer restarts are a normal thing in OpenCL world. So in order to compensate the risk I've implemented extra measures for type-safety. Basically I've used nominal types everywhere where possible (search for type discrimination). I.e. types which basically allow to distinguish two similar atomic (or non-atomic) type, example:
export type Kilos<T> = T & { readonly discriminator: unique symbol };
export type Pounds<T> = T & { readonly discriminator: unique symbol };
export interface MetricWeight {
value: Kilos<number>
}
export interface ImperialWeight {
value: Pounds<number>
}
const wm: MetricWeight = { value: 0 as Kilos<number> }
const wi: ImperialWeight = { value: 0 as Pounds<number> }
wm.value = wi.value; // Gives compiler error
wi.value = wi.value * 2; // Gives compiler error
wm.value = wi.value * 2; // Gives compiler error
const we: MetricWeight = { value: 0 } // Gives compiler error
It improves the TypeSafety keeps notion of original type but comes with additional strain of casting as Kilos<number> here and there, though it shouldn't be a problem due to risk compensation (I guess).
This is an early implementation of Node.JS bindings to OpenCL supporting all features of OpenCL up to the latests specification available on Khronos.org.
This implementation is different from node-webcl in the sense that it is close to OpenCL C host methods. A WebCL object model would be available later by simply wrapping the low level methods of node-opencl.
The test/ folder will contain as many unit tests testing all features of OpenCL. These tests are not based on Khronos conformance tests, though they should be similar. The goals of these tests is to check OpenCL drivers to discover their bugs on various platforms and, if possible, implement remedies while companies correct their drivers.
The implementation is compliant to OpenCL 1.1, 1.2 and 2.0 in terms of method support. Presence of these methods depend on the version of OpenCL supported by your driver.
Compliant to node.js 4.x architecture and NAN 2.x. Due to the extensive changes in v8, we don't support earlier versions of node.js.
This project has been succesfully tested on the following platforms :
We only support 64-bit operating systems, though 32-bit OS should work too.
Dependencies:
Except specific platform installation guides below, you only need to install the package through
npm install
To run unit tests, you will need mocha as a global package. Then you can simply call
npm test
You should only need :
The easiest way to get the projet running with an Intel CPU or an AMD CPU/GPU/APU is by using AMD APP SDK.
You can use the included Dockerfile for an example with Ubuntu.
This dockerfile is based on the following guide : http://streamcomputing.eu/blog/2011-06-24/install-opencl-on-debianubuntu-orderly/
You need at least:
Please note that while node-gyp should work for compilation, it is possible that another DLL will be used on dynamic linking, leading to errors.
You need to update your path in order to to get AMD APP SDK's OpenCL.dll first in path resolution order.
For now you can simply require this project and call native-like functions on the global object returned.
The API is very close to the low-level one, although there are minor changes when it comes to lengths and, of course, pointers.
Depending on your OS and the OpenCL implementation you're using, you will get different behaviours that do not always correspond to the one given in Khronos specifications. For now we do not correct them, but we have put warnings when running tests that trigger those behaviours so you can run them to check if it is a known issue.
Javascript does not support 64 bits integers however OpenCL returns Int64 values for mem-size related functions like getDeviceInfo, getKernelWorkGroupInfo and time-related function getEventProfilingInfo. In order to deal with the limitation for getDeviceInfo, getKernelWorkGroupInfo would return the amounts in kilobytes. For getEventProfilingInfo we return an array of two 32 bit integers that form the resulting Int64 value, if necessary the resulting value can be gathered together using formula value = (hi << 32) | lo however in absolute majority of cases only lower 32 bits of 64 bit integer are required.
By adding true instead of creating a cl.Event (as in webcl) to any enqueueXXX() methods, the enqueueXXX() returns a cl.Event that can be used to coordinate calls, profiling etc...
Due to changes in Chrome v8 embedded in node 4.x, buffers can only be ArrayBuffer or Buffer, or derivative. Using Javascript Array will throw exceptions.
Pull requests are welcome! When you do a PR on this project, you need to respect the following rules :
This project is under a BSD 3-Clause licence.
FAQs
A binding to OpenCL for Node.JS
We found that node-opencl-ts demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.