https://github.com/mkrufky/node-async-factory-worker
An asynchronous work helper - Asyncronously construct arbitrary C++ objects and deliver to the main Node.js thread in native code even without a public copy constructor
https://github.com/mkrufky/node-async-factory-worker
Last synced: 6 months ago
JSON representation
An asynchronous work helper - Asyncronously construct arbitrary C++ objects and deliver to the main Node.js thread in native code even without a public copy constructor
- Host: GitHub
- URL: https://github.com/mkrufky/node-async-factory-worker
- Owner: mkrufky
- License: mit
- Created: 2018-05-26T16:14:36.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-06-09T15:48:09.000Z (over 7 years ago)
- Last Synced: 2025-03-23T17:01:45.255Z (7 months ago)
- Language: C++
- Homepage:
- Size: 85 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# async-factory-worker
Asyncronously construct arbitrary C++ objects and classes even without a public copy constructor
[](https://nodei.co/npm/async-factory-worker/)
[](http://travis-ci.org/mkrufky/node-async-factory-worker)
[](https://ci.appveyor.com/project/mkrufky/node-async-factory-worker/branch/master)
async-factory-worker is a header package for building c++ native addons for node.js that is meant to complement **[nan](https://github.com/nodejs/nan)**
## Usage
Simply add **nan** and **async-factory-worker** as dependencies in the *package.json* of your Node addon:
``` bash
$ npm install --save nan
$ npm install --save async-factory-worker
```
Pull in the paths to **nan** and **async-factory-worker** in your *binding.gyp* so that you can use `#include ` in your *.cpp* files:
``` python
"include_dirs" : [
"` when compiling your addon.
## API
`AsyncFactoryWorker` is an _abstract_ class that you can subclass to have much of the annoying asynchronous queuing and handling taken care of for you. It can even store arbitrary V8 objects for you and have them persist while the asynchronous work is in progress.
This class internally handles the details of creating an [`AsyncResource`](https://github.com/nodejs/nan/tree/master/doc/node_misc.md#AsyncResource), and running the callback in the
correct async context. To be able to identify the async resources created by this class in async-hooks, provide a
`resource_name` to the constructor. It is recommended that the module name be used as a prefix to the `resource_name` to avoid
collisions in the names. For more details see [`AsyncResource`](https://github.com/nodejs/nan/tree/master/doc/node_misc.md#AsyncResource) documentation. The `resource_name` needs to stay valid for the lifetime of the worker instance.
`AsyncFactoryWorker` is an _abstract_ class template that extends [`Nan::AsyncWorker`](https://github.com/nodejs/nan/blob/master/doc/asyncworker.md#api_nan_async_worker) and adds additional progress reporting callbacks that can be used during the asynchronous work execution to provide progress data back to JavaScript.
`AsyncFactoryWorker` behaves exactly the same as [`Nan::AsyncProgressQueueWorker`](https://github.com/nodejs/nan/blob/master/doc/asyncworker.md#api_nan_async_progress_queue_worker), except `AsyncFactoryWorker` avoids the copy. Data is constructed once and delivered to the receiving thread. Just as [`Nan::AsyncProgressQueueWorker`](https://github.com/nodejs/nan/blob/master/doc/asyncworker.md#api_nan_async_progress_queue_worker), all events are queued and delivered to the main thread.
Definition:
```c++
template
class AsyncFactoryWorker : public AsyncWorker {
public:
explicit AsyncFactoryWorker(Callback *callback_, const char* resource_name = "nan:mkrufky:AsyncFactoryWorker");
virtual ~AsyncFactoryWorker();
void WorkProgress();
class ExecutionProgress {
public:
void Construct(Targs... Fargs) const;
};
virtual void Execute(const ExecutionProgress& progress) = 0;
virtual void HandleProgressCallback(const T *data, size_t count) = 0;
virtual void Destroy();
};
```
This works just like the [`Nan::AsyncProgressQueueWorker`](https://github.com/nodejs/nan/blob/master/doc/asyncworker.md#api_nan_async_progress_queue_worker), but instead of `std::copy`ing the data, the `progress.Construct` function passes along the object constructor arguments, constructing and delivering the object to the main thread.
It allows us to asyncronously construct C++ objects even if they lack a public copy constructor, although it also does support copy constructors.
Sure, the constructor arguments end up getting copied, but not the entire object, which only gets constructed once. Depending on the code being built around this worker, this could make things much more efficient.
Since `AsyncFactoryWorker` uses a variadic template, one can use it in many different ways. Pass no constructor arguments to use the default constructor. One can even use `&&T` as the constructor arguments and the worker will use the `move` constructor!!
### Tests
To run the async-factory-worker tests do:
``` sh
npm install
npm run-script rebuild-tests
npm test
```
Or just:
``` sh
npm install
make test
```
## Licence & copyright
Copyright (c) 2018 Michael Ira Krufky
async-factory-worker is licensed under an MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.