async-factory-worker

async-factory-worker

Asyncronously construct arbitrary C++ objects and classes even without a public copy constructor

async-factory-worker is a header package for building c++ native addons for node.js that is meant to complement nan

Usage

Simply add nan and async-factory-worker as dependencies in the package.json of your Node addon:

$ 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 <async_factory_worker.h> in your .cpp files:

"include_dirs" : [
    "<!(node -e \"require('nan')\")",
    "<!(node -e \"require('async-factory-worker')\")"
]

This works like a -I<path-to-async-factory-worker> 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, 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 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 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, except AsyncFactoryWorker avoids the copy. Data is constructed once and delivered to the receiving thread. Just as Nan::AsyncProgressQueueWorker, all events are queued and delivered to the main thread.

Definition:

template<class T, typename... Targs>
class AsyncFactoryWorker<T, Targs...> : 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, but instead of std::copying 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:

npm install
npm run-script rebuild-tests
npm test

Or just:

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.