node_modules/node-pty/node_modules/nan/doc/asyncworker.md

   1 ## Asynchronous work helpers
   2
   3 `Nan::AsyncWorker`, `Nan::AsyncProgressWorker` and `Nan::AsyncProgressQueueWorker` 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_progress_queue_worker"><b><code>Nan::AsyncProgressQueueWorker</code></b></a>
   8  - <a href="#api_nan_async_queue_worker"><b><code>Nan::AsyncQueueWorker</code></b></a>
   9
  10 <a name="api_nan_async_worker"></a>
  11 ### Nan::AsyncWorker
  12
  13 `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.
  14
  15 This class internally handles the details of creating an [`AsyncResource`][AsyncResource], and running the callback in the
  16 correct async context. To be able to identify the async resources created by this class in async-hooks, provide a
  17 `resource_name` to the constructor. It is recommended that the module name be used as a prefix to the `resource_name` to avoid
  18 collisions in the names. For more details see [`AsyncResource`][AsyncResource] documentation.  The `resource_name` needs to stay valid for the lifetime of the worker instance.
  19
  20 Definition:
  21
  22 ```c++
  23 class AsyncWorker {
  24  public:
  25   explicit AsyncWorker(Callback *callback_, const char* resource_name = "nan:AsyncWorker");
  26
  27   virtual ~AsyncWorker();
  28
  29   virtual void WorkComplete();
  30
  31   void SaveToPersistent(const char *key, const v8::Local<v8::Value> &value);
  32
  33   void SaveToPersistent(const v8::Local<v8::String> &key,
  34                         const v8::Local<v8::Value> &value);
  35
  36   void SaveToPersistent(uint32_t index,
  37                         const v8::Local<v8::Value> &value);
  38
  39   v8::Local<v8::Value> GetFromPersistent(const char *key) const;
  40
  41   v8::Local<v8::Value> GetFromPersistent(const v8::Local<v8::String> &key) const;
  42
  43   v8::Local<v8::Value> GetFromPersistent(uint32_t index) const;
  44
  45   virtual void Execute() = 0;
  46
  47   uv_work_t request;
  48
  49   virtual void Destroy();
  50
  51  protected:
  52   Persistent<v8::Object> persistentHandle;
  53
  54   Callback *callback;
  55
  56   virtual void HandleOKCallback();
  57
  58   virtual void HandleErrorCallback();
  59
  60   void SetErrorMessage(const char *msg);
  61
  62   const char* ErrorMessage();
  63 };
  64 ```
  65
  66 <a name="api_nan_async_progress_worker"></a>
  67 ### Nan::AsyncProgressWorkerBase &amp; Nan::AsyncProgressWorker
  68
  69 `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.
  70
  71 Previously the definition 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.
  72
  73 `Nan::AsyncProgressWorkerBase` &amp; `Nan::AsyncProgressWorker` is intended for best-effort delivery of nonessential progress messages, e.g. a progress bar.  The last event sent before the main thread is woken will be delivered.
  74
  75 Definition:
  76
  77 ```c++
  78 template<class T>
  79 class AsyncProgressWorkerBase<T> : public AsyncWorker {
  80  public:
  81   explicit AsyncProgressWorkerBase(Callback *callback_, const char* resource_name = ...);
  82
  83   virtual ~AsyncProgressWorkerBase();
  84
  85   void WorkProgress();
  86
  87   class ExecutionProgress {
  88    public:
  89     void Signal() const;
  90     void Send(const T* data, size_t count) const;
  91   };
  92
  93   virtual void Execute(const ExecutionProgress& progress) = 0;
  94
  95   virtual void HandleProgressCallback(const T *data, size_t count) = 0;
  96
  97   virtual void Destroy();
  98 };
  99
 100 typedef AsyncProgressWorkerBase<T> AsyncProgressWorker;
 101 ```
 102
 103 <a name="api_nan_async_progress_queue_worker"></a>
 104 ### Nan::AsyncProgressQueueWorker
 105
 106 `Nan::AsyncProgressQueueWorker` 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.
 107
 108 `Nan::AsyncProgressQueueWorker` behaves exactly the same as `Nan::AsyncProgressWorker`, except all events are queued and delivered to the main thread.
 109
 110 Definition:
 111
 112 ```c++
 113 template<class T>
 114 class AsyncProgressQueueWorker<T> : public AsyncWorker {
 115  public:
 116   explicit AsyncProgressQueueWorker(Callback *callback_, const char* resource_name = "nan:AsyncProgressQueueWorker");
 117
 118   virtual ~AsyncProgressQueueWorker();
 119
 120   void WorkProgress();
 121
 122   class ExecutionProgress {
 123    public:
 124     void Send(const T* data, size_t count) const;
 125   };
 126
 127   virtual void Execute(const ExecutionProgress& progress) = 0;
 128
 129   virtual void HandleProgressCallback(const T *data, size_t count) = 0;
 130
 131   virtual void Destroy();
 132 };
 133 ```
 134
 135 <a name="api_nan_async_queue_worker"></a>
 136 ### Nan::AsyncQueueWorker
 137
 138 `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`.
 139
 140 Definition:
 141
 142 ```c++
 143 void AsyncQueueWorker(AsyncWorker *);
 144 ```
 145
 146 [AsyncResource]: node_misc.md#api_nan_asyncresource