www.aleph1.co.uk Git - yaffs-website/blob - node_modules/nan/doc/asyncworker.md

   1 ## Asynchronous work helpers
   2
   3 `Nan::AsyncWorker` and `Nan::AsyncProgressWorker` are helper classes that make working with asynchronous code easier.
   4
   5  - <a href="#api_nan_async_worker"><b><code>Nan::AsyncWorker</code></b></a>
   6  - <a href="#api_nan_async_progress_worker"><b><code>Nan::AsyncProgressWorkerBase &amp; Nan::AsyncProgressWorker</code></b></a>
   7  - <a href="#api_nan_async_queue_worker"><b><code>Nan::AsyncQueueWorker</code></b></a>
   8
   9 <a name="api_nan_async_worker"></a>
  10 ### Nan::AsyncWorker
  11
  12 `Nan::AsyncWorker` 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.
  13
  14 Definition:
  15
  16 ```c++
  17 class AsyncWorker {
  18  public:
  19   explicit AsyncWorker(Callback *callback_);
  20
  21   virtual ~AsyncWorker();
  22
  23   virtual void WorkComplete();
  24
  25   void SaveToPersistent(const char *key, const v8::Local<v8::Value> &value);
  26
  27   void SaveToPersistent(const v8::Local<v8::String> &key,
  28                         const v8::Local<v8::Value> &value);
  29
  30   void SaveToPersistent(uint32_t index,
  31                         const v8::Local<v8::Value> &value);
  32
  33   v8::Local<v8::Value> GetFromPersistent(const char *key) const;
  34
  35   v8::Local<v8::Value> GetFromPersistent(const v8::Local<v8::String> &key) const;
  36
  37   v8::Local<v8::Value> GetFromPersistent(uint32_t index) const;
  38
  39   virtual void Execute() = 0;
  40
  41   uv_work_t request;
  42
  43   virtual void Destroy();
  44
  45  protected:
  46   Persistent<v8::Object> persistentHandle;
  47
  48   Callback *callback;
  49
  50   virtual void HandleOKCallback();
  51
  52   virtual void HandleErrorCallback();
  53
  54   void SetErrorMessage(const char *msg);
  55
  56   const char* ErrorMessage();
  57 };
  58 ```
  59
  60 <a name="api_nan_async_progress_worker"></a>
  61 ### Nan::AsyncProgressWorkerBase &amp; Nan::AsyncProgressWorker
  62
  63 `Nan::AsyncProgressWorkerBase` 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.
  64
  65 Previously the definiton of `Nan::AsyncProgressWorker` only allowed sending `const char` data. Now extending `Nan::AsyncProgressWorker` will yield an instance of the implicit `Nan::AsyncProgressWorkerBase` template with type `<char>` for compatibility.
  66
  67 Definition:
  68
  69 ```c++
  70 template<class T>
  71 class AsyncProgressWorkerBase<T> : public AsyncWorker {
  72  public:
  73   explicit AsyncProgressWorker(Callback *callback_);
  74
  75   virtual ~AsyncProgressWorker();
  76
  77   void WorkProgress();
  78
  79   class ExecutionProgress {
  80    public:
  81     void Signal() const;
  82     void Send(const T* data, size_t size) const;
  83   };
  84
  85   virtual void Execute(const ExecutionProgress& progress) = 0;
  86
  87   virtual void HandleProgressCallback(const T *data, size_t size) = 0;
  88
  89   virtual void Destroy();
  90
  91 typedef AsyncProgressWorkerBase<T> AsyncProgressWorker;
  92 ```
  93
  94 <a name="api_nan_async_queue_worker"></a>
  95 ### Nan::AsyncQueueWorker
  96
  97 `Nan::AsyncQueueWorker` will run a `Nan::AsyncWorker` asynchronously via libuv. Both the `execute` and `after_work` steps are taken care of for you. Most of the logic for this is embedded in `Nan::AsyncWorker`.
  98
  99 Definition:
 100
 101 ```c++
 102 void AsyncQueueWorker(AsyncWorker *);
 103 ```