[
{
"path": ".gitignore",
"content": "bin\nbuild\nnode_modules\ntypes\n\n# ignore all js files under lib except explicit ones specified here\nlib/**/*.js\n!lib/core/*.js\n!lib/zone/zone-main.js\n!lib/binding.js\n\n# ignore all js files under test\ntest/**/*.js\ntest/module/test-dir\ntest/module/test-file\n!test/module/node_modules\n!test/module/**/*.js\n\n!unittest/module/test-files/node_modules\n\n# ignore all js files under benchmark\nbenchmark/**/*.js\n\npackage-lock.json\n\n!tsconfig.json\n\n# ignore all VSCode files\n.vscode\n\n# ignore npm related files\nnpm-debug.log\n"
},
{
"path": ".npmignore",
"content": "bin\nbuild\nexamples\n\n# Exclude TypeScript source files.\nbenchmark/**/*.ts\nbenchmark/tsconfig.json\nlib/**/*.ts\nlib/tsconfig.json\ntest/**/*.ts\ntest/module/test-dir\ntest/module/test-file\ntest/tsconfig.json\n\n.vscode\n.npmrc\n.npmignore\n.taskkey\n.travis.yml\nappveyor.yml\nnpm-debug.log\n"
},
{
"path": ".travis.yml",
"content": "language: node_js\ncompiler: default\nmatrix:\n exclude:\n # Disable the default build and use customized matrix only.\n - compiler: default\n include:\n # Node 6.x Linux (Precise) G++5.4.1\n - os: linux\n dist: precise\n node_js: '6'\n compiler: g++-5\n addons:\n apt:\n # The apt source 'ubuntu-toolchain-r-test' is for GCC 5+\n # The apt source 'george-edison55-precise-backports' is for CMake 3.2+\n sources:\n - ubuntu-toolchain-r-test\n - george-edison55-precise-backports\n packages:\n - g++-5\n - cmake-data\n - cmake\n env:\n - COMPILER_OVERRIDE=\"CXX=g++-5 CC=gcc-5\"\n # Node 6.x OS X (Yosemite) AppleClang 6.1\n - os: osx\n node_js: '6'\n osx_image: xcode6.4\n # Node LTS (8.x) Linux (Trusty) G++6.4.0\n - os: linux\n dist: trusty\n node_js: '8'\n compiler: g++-6\n addons:\n apt:\n sources:\n - ubuntu-toolchain-r-test\n packages:\n - g++-6\n env:\n - COMPILER_OVERRIDE=\"CXX=g++-6 CC=gcc-6\"\n # Node LTS (8.x) OS X (El Capitan) AppleClang 7.3\n - os: osx\n node_js: '8'\n osx_image: xcode7.3\n # Node (9.x) Linux (Trusty) G++6.4.0\n - os: linux\n dist: trusty\n node_js: '9'\n compiler: g++-6\n addons:\n apt:\n sources:\n - ubuntu-toolchain-r-test\n packages:\n - g++-6\n env:\n - COMPILER_OVERRIDE=\"CXX=g++-6 CC=gcc-6\"\n # Node (9.x) macOS (Sierra) AppleClang 8.1\n - os: osx\n node_js: '9'\n osx_image: xcode8.3\n # Node Current (10.x) Linux (Trusty) G++7.3.0\n - os: linux\n dist: trusty\n node_js: '10'\n compiler: g++-7\n addons:\n apt:\n sources:\n - ubuntu-toolchain-r-test\n packages:\n - g++-7\n env:\n - COMPILER_OVERRIDE=\"CXX=g++-7 CC=gcc-7\"\n # Node Current (10.x) macOS (High Sierra) AppleClang 9.1\n - os: osx\n node_js: '10'\n osx_image: xcode9.3\n\nbefore_install:\n- |\n if [ $TRAVIS_OS_NAME == linux ]; then\n export ${COMPILER_OVERRIDE}\n fi\ninstall:\n- npm install cmake-js -g\n- npm install --no-fetch\nscript:\n- npm test\n- npm run unittest\n"
},
{
"path": "CMakeLists.txt",
"content": "cmake_minimum_required(VERSION 3.2 FATAL_ERROR)\n\nproject(\"napa\")\n\nset(CMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELEASE ${PROJECT_SOURCE_DIR}/bin)\nset(CMAKE_ARCHIVE_OUTPUT_DIRECTORY_DEBUG ${PROJECT_SOURCE_DIR}/bin)\nset(CMAKE_LIBRARY_OUTPUT_DIRECTORY_RELEASE ${PROJECT_SOURCE_DIR}/bin)\nset(CMAKE_LIBRARY_OUTPUT_DIRECTORY_DEBUG ${PROJECT_SOURCE_DIR}/bin)\nset(CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE ${PROJECT_SOURCE_DIR}/bin)\nset(CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG ${PROJECT_SOURCE_DIR}/bin)\n\n# Require Cxx14 features\nset(CMAKE_CXX_STANDARD 14)\nset(CMAKE_CXX_STANDARD_REQUIRED ON)\n\nif (NOT WIN32 AND NOT APPLE)\n # Set symbol visibility to hidden by default.\n # Napa shared library shares a few classes with napa-binding.node with different compile definition,\n # exposing the same symbols from both shared libraries may cause improper behaviors under gcc.\n set(CMAKE_CXX_VISIBILITY_PRESET hidden)\n set(CMAKE_VISIBILITY_INLINES_HIDDEN)\n\n # Prevent symbol relocations internal to our wrapper library to be overwritten by the application.\n set (CMAKE_SHARED_LINKER_FLAGS \"${CMAKE_SHARED_LINKER_FLAGS} -Wl,-Bsymbolic -Wl,-Bsymbolic-functions\")\n set (CMAKE_MODULE_LINKER_FLAGS \"${CMAKE_MODULE_LINKER_FLAGS} -Wl,-Bsymbolic -Wl,-Bsymbolic-functions\")\n\n # Mark object non-lazy runtime binding.\n set (CMAKE_SHARED_LINKER_FLAGS \"${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,now\")\n set (CMAKE_MODULE_LINKER_FLAGS \"${CMAKE_MODULE_LINKER_FLAGS} -Wl,-z,now\")\nendif ()\n\n# Build napa shared library.\nadd_subdirectory(src)\n\nif (CMAKE_JS_VERSION)\n # Build napa addon for node.\n add_subdirectory(node)\n add_subdirectory(test/module/addon)\nendif()\n"
},
{
"path": "LICENSE.txt",
"content": "Napa.JS\n\nCopyright (c) Microsoft Corporation. All rights reserved. \n\nMIT License\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"\"Software\"\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n"
},
{
"path": "README.md",
"content": "[](https://travis-ci.org/Microsoft/napajs)\n[](https://ci.appveyor.com/project/napajs/napajs)\n[](https://www.npmjs.com/package/napajs)\n[](https://www.npmjs.com/package/napajs)\n\n# Napa.js\nNapa.js is a multi-threaded JavaScript runtime built on [V8](https://github.com/v8/v8), which was originally designed to develop highly iterative services with non-compromised performance in Bing. As it evolves, we find it useful to complement [Node.js](https://nodejs.org) in CPU-bound tasks, with the capability of executing JavaScript in multiple V8 isolates and communicating between them. Napa.js is exposed as a Node.js module, while it can also be embedded in a host process without Node.js dependency.\n\n## Installation\nInstall the latest stable version:\n```\nnpm install napajs\n```\nOther options can be found in [Build Napa.js](https://github.com/Microsoft/napajs/wiki/build-napa.js).\n\n## Quick Start\n```js\nconst napa = require('napajs');\nconst zone1 = napa.zone.create('zone1', { workers: 4 });\n\n// Broadcast code to all 4 workers in 'zone1'.\nzone1.broadcast('console.log(\"hello world\");');\n\n// Execute an anonymous function in any worker thread in 'zone1'.\nzone1.execute(\n (text) => text, \n ['hello napa'])\n .then((result) => {\n console.log(result.value);\n });\n```\nMore examples:\n* [Estimate PI in parallel](./examples/tutorial/estimate-pi-in-parallel)\n* [Max sub-matrix of 1s with layered parallelism](./examples/tutorial/max-square-sub-matrix)\n* [Parallel Quick Sort](./examples/tutorial/parallel-quick-sort)\n* [Recursive Fibonacci with multiple JavaScript threads](./examples/tutorial/recursive-fibonacci)\n* [Synchronized loading](./examples/tutorial/synchronized-loading)\n\n## Features\n- Multi-threaded JavaScript runtime.\n- Node.js compatible module architecture with NPM support.\n- API for object transportation, object sharing and synchronization across JavaScript threads.\n- API for pluggable logging, metric and memory allocator.\n- Distributed as a Node.js module, as well as supporting embed scenarios.\n\n## Documentation\n- [Napa.js Home](https://github.com/Microsoft/napajs/wiki)\n- [API Reference](./docs/api/index.md)\n- [FAQ](https://github.com/Microsoft/napajs/wiki/FAQ)\n\n# Contribute\nYou can contribute to Napa.js in following ways:\n\n* [Report issues](https://github.com/Microsoft/napajs/issues) and help us verify fixes as they are checked in.\n* Review the [source code changes](https://github.com/Microsoft/napajs/pulls).\n* Contribute to core module compatibility with Node.\n* Contribute bug fixes.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact opencode@microsoft.com with any additional questions or comments.\n\n# License\nCopyright (c) Microsoft Corporation. All rights reserved.\n\nLicensed under the [MIT](https://github.com/Microsoft/napajs/blob/master/LICENSE.txt) License.\n"
},
{
"path": "appveyor.yml",
"content": "environment:\n matrix:\n # Windows Server 2012 R2 Visual C++ Build Tools 2015\n - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015\n nodejs_version: 6\n # Windows Server 2012 R2 Visual C++ Build Tools 2015\n - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015\n nodejs_version: 8\n # Windows Server 2016 Visual C++ Build Tools 2017\n - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017\n nodejs_version: 9\n # Windows Server 2016 Visual C++ Build Tools 2017\n - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017\n nodejs_version: 10\n\nplatform:\n- x64\n\ninstall:\n- ps: Install-Product node $env:nodejs_version $env:platform\n- npm install cmake-js -g\n- npm install --no-fetch\n\n# Skip MSBuild stage\nbuild: off\n\ntest_script:\n- npm test\n- npm run unittest\n"
},
{
"path": "benchmark/README.md",
"content": "# Benchmark\n\n## Summary\n- JavaScript execution in napajs is on par with node, using the same version of V8, which is expected.\n- `zone.execute` scales linearly on number of workers, which is expected.\n- The overhead of calling `zone.execute` from node is around 0.1ms after warm-up. The cost of using anonymous function is neglectable.\n- `transport.marshall` cost on small plain JavaScript values is about 3x of JSON.stringify.\n- The overhead of `store.set` and `store.get` is around 0.06ms plus transport overhead on the objects.\n\nWe got this report on environment below:\n\n| Name | Value |\n|-------------------|---------------------------------------------------------------------------------------|\n|**Processor** |Intel(R) Xeon(R) CPU L5640 @ 2.27GHz, 8 virtual processors |\n|**System Type** |x64-based PC |\n|**Physical Memory**|16.0 GB |\n|**OS version** |Microsoft Windows Server 2012 R2 |\n\n\n## Napa vs. Node on JavaScript execution \nPlease refer to [node-napa-perf-comparison.ts](node-napa-perf-comparison.ts).\n\n| node time | napa time |\n| --------- | --------- |\n| 3026.76 | 3025.81 |\n\n## Linear scalability\n`zone.execute` scales linearly on number of workers. We performed 1M CRC32 calls on a 1024-length string on each worker, here are the numbers. We still need to understand why the time of more workers running parallel would beat less workers.\n\n| | node | napa - 1 worker | napa - 2 workers | napa - 4 workers | napa - 8 workers |\n| ------- | ----------- | --------------- | ---------------- | ---------------- | ---------------- |\n| time | 8,649521600 | 6146.98 | 4912.57 | 4563.48 | 6168.41 |\n| cpu% | ~15% | ~15% | ~27% | ~55% | ~99% |\n\nPlease refer to [execute-scalability.ts](./execute-scalability.ts) for test details.\n\n## Execute overhead\nThe overhead of `zone.execute` includes\n1. Marshalling cost of arguments in caller thread.\n2. Queuing time before a worker can execute.\n3. Unmarshalling cost of arguments in target worker.\n4. Marshalling cost of return value from target worker.\n5. Queuing time before caller callback is notified. \n6. Unmarshalling cost of return value in caller thread.\n\nIn this section we will examine #2 and #5. So we use empty function with no arguments and no return value.\n\nTransport overhead (#1, #3, #4, #6) varies by size and complexity of payload, will be benchmarked separately in [Transport Overhead](#transport-overhead) section.\n\nPlease refer to [execute-overhead.ts](./execute-overhead.ts) for test details.\n\n### Overhead after warm-up\nAverage overhead is around 0.06ms to 0.12ms for `zone.execute`.\n\n| repeat | zone.execute (ms) |\n|----------|-------------------|\n| 200 | 24.932 |\n| 5000 | 456.893 |\n| 10000 | 810.687 |\n| 50000 | 3387.361 |\n\n*10000 times of zone.execute on anonymous function is 807.241ms. The gap is within range of bench noise.\n\n### Overhead during warm-up:\n\n| Sequence of call | Time (ms) |\n|------------------|-----------|\n| 1 | 6.040 |\n| 2 | 4.065 |\n| 3 | 5.250 |\n| 4 | 4.652 |\n| 5 | 1.572 |\n| 6 | 1.366 |\n| 7 | 1.403 |\n| 8 | 1.213 |\n| 9 | 0.450 |\n| 10 | 0.324 |\n| 11 | 0.193 |\n| 12 | 0.238 |\n| 13 | 0.191 |\n| 14 | 0.230 |\n| 15 | 0.203 |\n| 16 | 0.188 |\n| 17 | 0.188 |\n| 18 | 0.181 |\n| 19 | 0.185 |\n| 20 | 0.182 |\n\n\n## Transport overhead\n\nThe overhead of `transport.marshall` includes\n1. overhead of needing replacer callback during JSON.stringify. (even an empty callback will slow down JSON.stringify significantly)\n2. traverse every value during JSON.stringify, to check value type and get `cid` to put into payload.\n - a. If value doesn't need special care.\n - b. If value is a transportable object that needs special care.\n\n2.b is related to individual transportable classes, which may vary per individual class. Thus we examine #1 and #2.a in this test.\n\nThe overhead of `transport.unmarshall` includes\n1. overhead of needing reviver callback during JSON.parse.\n2. traverse every value during JSON.parse, to check if object has `_cid` property.\n - a. If value doesn't have property `_cid`.\n - b. Otherwise, find constructor and call the [`Transportable.marshall`](../docs/api/transport.md#transportable-marshall).\n\nWe also evaluate only #1, #2.a in this test.\n\nPlease refer to [transport-overhead.ts](./transport-overhead.ts) for test details.\n\n\\*All operations are repeated for 1000 times.\n\n| payload type | size | JSON.stringify (ms) | transport.marshall (ms) | JSON.parse (ms) | transport.unmarshall (ms) |\n| ---------------------------------- | ----- | ------------------- | ----------------------- | --------------- | ------------------------- |\n| 1 level - 10 integers | 91 | 4.90 | 18.05 (3.68x) | 3.50 | 17.98 (5.14x) |\n| 1 level - 100 integers | 1081 | 65.45 | 92.78 (1.42x) | 20.45 | 122.25 (5.98x) |\n| 10 level - 2 integers | 18415 | 654.40 | 2453.37 (3.75x) | 995.02 | 2675.72 (2.69x) |\n| 2 level - 10 integers | 991 | 19.74 | 66.82 (3.39x) | 27.85 | 138.45 (4.97x) |\n| 3 level - 5 integers | 1396 | 33.66 | 146.33 (4.35x) | 51.54 | 189.07 (3.67x) |\n| 1 level - 10 strings - length 10 | 201 | 3.81 | 10.17 (2.67x) | 9.46 | 20.81 (2.20x) |\n| 1 level - 100 strings - length 10 | 2191 | 76.53 | 115.74 (1.51x) | 77.71 | 181.24 (2.33x) |\n| 2 level - 10 strings - length 10 | 2091 | 30.15 | 97.65 (3.24x) | 95.51 | 213.20 (2.23x) |\n| 3 level - 5 strings - length 10 | 2646 | 41.95 | 155.42 (3.71x) | 123.82 | 227.90 (1.84x) |\n| 1 level - 10 strings - length 100 | 1101 | 7.74 | 12.19 (1.57x) | 17.34 | 29.83 (1.72x) |\n| 1 level - 100 strings - length 100 | 11191 | 66.17 | 112.83 (1.71x) | 197.67 | 282.63 (1.43x) |\n| 2 level - 10 strings - length 100 | 11091 | 68.46 | 149.99 (2.19x) | 202.85 | 298.19 (1.47x) |\n| 3 level - 5 integers | 13896 | 89.46 | 208.21 (2.33x) | 265.25 | 418.42 (1.58x) |\n| 1 level - 10 booleans | 126 | 2.84 | 8.14 (2.87x) | 3.06 | 14.20 (4.65x) |\n| 1 level - 100 booleans | 1341 | 20.28 | 59.36 (2.93x) | 21.59 | 121.15 (5.61x) |\n| 2 level - 10 booleans | 1341 | 23.92 | 89.62 (3.75x) | 31.84 | 137.92 (4.33x) |\n| 3 level - 5 booleans | 1821 | 36.15 | 138.24 (3.82x) | 55.71 | 195.50 (3.51x) |\n\n## Store access overhead\n\nThe overhead of `store.set` includes\n1. Overhead of calling `transport.marshall` on value.\n2. Overhead of put marshalled data and transport context into C++ map (with exclusive_lock).\n\nThe overhead of `store.get` includes\n1. Overhead of getting marshalled data and transport context from C++ map (with shared_lock).\n2. Overhead of calling `transport.unmarshall` on marshalled data.\n\nFor `store.set`, numbers below indicates the cost beyond marshall is around 0.07~0.4ms varies per payload size. (10B to 18KB). `store.get` takes a bit more: 0.06~0.9ms with the same payload size variance. If the value in store is not updated frequently, it's always good to cache it in JavaScript world.\n\nPlease refer to [store-overhead.ts](./store-overhead.ts) for test details.\n\n\\*All operations are repeated for 1000 times.\n\n| payload type | size | transport.marshall (ms) | store.save (ms) | transport.unmarshall (ms) | store.get (ms) |\n| ---------------------------------- | ----- | ----------------------- | --------------- | ------------------------- | -------------- |\n| 1 level - 1 integers | 10 | 2.54 | 73.85 | 3.98 | 65.57 |\n| 1 level - 10 integers | 91 | 8.27 | 98.55 | 17.23 | 90.89 |\n| 1 level - 100 integers | 1081 | 97.10 | 185.31 | 144.75 | 274.39 |\n| 10 level - 2 integers | 18415 | 2525.18 | 2973.17 | 3093.06 | 3927.80 |\n| 2 level - 10 integers | 991 | 71.22 | 174.01 | 154.76 | 276.04 |\n| 3 level - 5 integers | 1396 | 127.06 | 219.73 | 182.27 | 337.59 |\n| 1 level - 10 strings - length 10 | 201 | 14.43 | 79.68 | 31.28 | 84.71 |\n| 1 level - 100 strings - length 10 | 2191 | 104.40 | 212.44 | 173.32 | 239.09 |\n| 2 level - 10 strings - length 10 | 2091 | 79.54 | 188.72 | 189.29 | 252.83 |\n| 3 level - 5 strings - length 10 | 2646 | 155.14 | 257.78 | 276.22 | 342.95 |\n| 1 level - 10 strings - length 100 | 1101 | 15.22 | 89.84 | 30.87 | 88.18 |\n| 1 level - 100 strings - length 100 | 11191 | 119.89 | 284.05 | 287.17 | 403.77 |\n| 2 level - 10 strings - length 100 | 11091 | 137.10 | 299.32 | 244.13 | 297.12 |\n| 3 level - 5 integers | 13896 | 183.84 | 310.89 | 285.80 | 363.50 |\n| 1 level - 10 booleans | 126 | 5.74 | 49.89 | 22.69 | 97.27 |\n| 1 level - 100 booleans | 1341 | 57.41 | 157.80 | 106.30 | 218.05 |\n| 2 level - 10 booleans | 1341 | 76.93 | 150.25 | 104.02 | 185.82 |\n| 3 level - 5 booleans | 1821 | 102.47 | 171.44 | 150.42 | 207.27 |\n"
},
{
"path": "benchmark/bench-utils.ts",
"content": "// Copyright (c) Microsoft Corporation. All rights reserved.\n// Licensed under the MIT license.\n\n/// Utility function to generate object for testing. \n\nexport function generateString(length: number): string {\n return Array(length).join('x');\n}\n\nexport function generateObject(keys: number, depth: number, valueType: string = \"string\", valueLength = 7) {\n let object: any = {};\n for (let i = 0; i < keys; ++i) {\n let key = `key${i}`;\n let value: any = null;\n if (depth > 1) {\n value = generateObject(keys, depth - 1, valueType, valueLength);\n }\n else if (valueType === 'string') {\n // We try to make each string different.\n value = generateString(valueLength - 1) + (depth * keys + i);\n }\n else if (valueType === 'number') {\n value = i;\n }\n else if (valueType === 'boolean') {\n value = i % 2 == 0;\n }\n object[key] = value;\n }\n return object;\n}\n\nexport function timeDiffInMs(diff: [number, number]): number {\n return (diff[0] * 1e9 + diff[1]) / 1e6;\n}\n\nexport function formatTimeDiff(diff: number | [number, number], printUnit: boolean = false): string {\n if (Array.isArray(diff)) {\n diff = timeDiffInMs(diff);\n }\n let message = diff.toFixed(2);\n if (printUnit) {\n message += \"ms\"\n }\n return message;\n}\n\nexport function formatRatio(dividend: number, divider: number): string {\n return \"(\" + (dividend / divider).toFixed(2) + \"x)\";\n}"
},
{
"path": "benchmark/bench.ts",
"content": "// Copyright (c) Microsoft Corporation. All rights reserved.\n// Licensed under the MIT license.\n\nimport * as napa from '../lib/index';\nimport * as nodeNapaPerfComp from './node-napa-perf-comparison';\nimport * as executeOverhead from './execute-overhead';\nimport * as executeScalability from './execute-scalability';\nimport * as transportOverhead from './transport-overhead';\nimport * as storeOverhead from './store-overhead';\n\nexport function bench(): Promise {\n // Non-zone related benchmarks.\n transportOverhead.bench();\n storeOverhead.bench();\n\n // Create zones for execute related benchmark.\n let singleWorkerZone = napa.zone.create('single-worker-zone', { workers: 1});\n let multiWorkerZone = napa.zone.create('multi-worker-zone', { workers: 8 });\n\n return nodeNapaPerfComp.bench(singleWorkerZone)\n .then(() => { return executeOverhead.bench(singleWorkerZone); })\n .then(() => { return executeScalability.bench(multiWorkerZone);});\n}\n\nbench();"
},
{
"path": "benchmark/execute-overhead.ts",
"content": "// Copyright (c) Microsoft Corporation. All rights reserved.\n// Licensed under the MIT license.\n\nimport * as napa from '../lib/index';\nimport * as mdTable from 'markdown-table';\nimport { formatTimeDiff } from './bench-utils';\n\nfunction batchExecuteOnNamedFunction(\n zone: napa.zone.Zone, \n repeat: number,\n args: any[]): Promise {\n \n return new Promise((resolve, reject) => {\n let finished = 0;\n let start = process.hrtime();\n for (let i = 0; i < repeat; ++i) {\n zone.execute(\"\", \"test\", args).then(() => {\n ++finished;\n if (finished === repeat) {\n resolve();\n }\n });\n }\n });\n}\n\nfunction batchExecuteOnAnonymousFunction(\n zone: napa.zone.Zone, \n repeat: number,\n args: any[]): Promise {\n \n return new Promise((resolve, reject) => {\n let finished = 0;\n let start = process.hrtime();\n for (let i = 0; i < repeat; ++i) {\n zone.execute(() => {}, args).then(() => {\n ++finished;\n if (finished === repeat) {\n resolve();\n }\n });\n }\n });\n}\n\nexport async function bench(zone: napa.zone.Zone): Promise {\n console.log(\"Benchmarking execute overhead...\");\n\n // Prepare a empty function.\n await zone.broadcast(\"function test() {}\");\n const ARGS = [1, \"hello\", {a: 1, b: true}];\n\n // Warm-up.\n const WARMUP_REPEAT: number = 20;\n\n console.log(\"## Execute overhead during warmup\\n\")\n let warmupTable = [];\n warmupTable.push([\"call #\", \"time (ms)\"]);\n for (let i = 0; i < WARMUP_REPEAT; ++i) {\n let start = process.hrtime();\n await zone.execute(\"\", \"test\", ARGS);\n warmupTable.push([i.toString(), formatTimeDiff(process.hrtime(start))]);\n }\n console.log(mdTable(warmupTable));\n\n // execute after warm-up\n const REPEAT: number = 10000;\n console.log(\"## `zone.execute` overhead (use function name)\\n\");\n let start = process.hrtime();\n await batchExecuteOnNamedFunction(zone, REPEAT, ARGS);\n console.log(`Elapse of running empty function by name for ${REPEAT} times: ${formatTimeDiff(process.hrtime(start), true)}\\n`);\n\n console.log(\"## `zone.execute` overhead (use anonymous function)\\n\");\n start = process.hrtime();\n await batchExecuteOnAnonymousFunction(zone, REPEAT, ARGS);\n console.log(`Elapse of running empty anonymous function for ${REPEAT} times: ${formatTimeDiff(process.hrtime(start), true)}\\n`);\n\n return;\n}"
},
{
"path": "benchmark/execute-scalability.ts",
"content": "// Copyright (c) Microsoft Corporation. All rights reserved.\n// Licensed under the MIT license.\n\nimport * as napa from '../lib/index';\nimport * as assert from 'assert';\nimport * as mdTable from 'markdown-table';\nimport { formatTimeDiff } from './bench-utils';\n\nfunction makeCRCTable(){\n var c;\n var crcTable = [];\n for(var n =0; n < 256; n++){\n c = n;\n for(var k =0; k < 8; k++){\n c = ((c&1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1));\n }\n crcTable[n] = c;\n }\n return crcTable;\n}\n\nlet crcTable = makeCRCTable();\nfunction crc32(str: string) {\n let crc = 0 ^ (-1);\n for (var i = 0; i < str.length; i++ ) {\n crc = (crc >>> 8) ^ crcTable[(crc ^ str.charCodeAt(i)) & 0xFF];\n }\n\n return (crc ^ (-1)) >>> 0;\n};\n\nfunction testCrc() {\n const REPEAT: number = 1000000;\n let result = 0;\n let key = Array(1024).join('x');\n for (let i = 0; i < REPEAT; ++i) {\n let hash = crc32(key);\n result = result ^ hash;\n }\n return result;\n}\n\nexport async function bench(zone: napa.zone.Zone): Promise {\n console.log(\"Benchmarking execute scalability...\");\n\n // Prepare a empty function.\n await zone.broadcast(makeCRCTable.toString());\n await zone.broadcast(\"var crcTable = makeCRCTable();\");\n await zone.broadcast(crc32.toString());\n await zone.broadcast(testCrc.toString());\n\n // Warm-up.\n let crcResult = testCrc();\n await zone.broadcast(\"testCrc()\");\n\n // Execute in Node with 1 thread.\n let start = process.hrtime();\n assert(testCrc() === crcResult);\n let nodeTime = formatTimeDiff(process.hrtime(start));\n\n let executeTime = {};\n let scalabilityTest = function(workers: number): Promise {\n let finished = 0;\n let start = process.hrtime();\n\n return new Promise((resolve, reject) => {\n for (let i = 0; i < workers; ++i) {\n zone.execute(\"\", \"testCrc\", []).then((result: napa.zone.Result) => {\n assert(crcResult === result.value);\n ++finished;\n if (finished === workers) {\n executeTime[workers] = formatTimeDiff(process.hrtime(start))\n resolve();\n }\n });\n }\n })\n };\n\n // Execute from 1 worker to 8 workers.\n await scalabilityTest(1);\n await scalabilityTest(2);\n await scalabilityTest(4);\n await scalabilityTest(8);\n console.log(\"## Execute scalability\\n\")\n console.log(mdTable([\n [\"node\", \"napa - 1 worker\", \"napa - 2 workers\", \"napa - 4 workers\", \"napa - 8 workers\"],\n [nodeTime, executeTime[1], executeTime[2], executeTime[4], executeTime[8]]\n ]));\n console.log('');\n}"
},
{
"path": "benchmark/node-napa-perf-comparison.ts",
"content": "// Copyright (c) Microsoft Corporation. All rights reserved.\n// Licensed under the MIT license.\n\nimport * as napa from '../lib/index';\nimport * as mdTable from 'markdown-table';\nimport { formatTimeDiff } from './bench-utils';\n\nexport function timeIt(func: () => void): [number, number] {\n let start = process.hrtime();\n func();\n return process.hrtime(start);\n}\n\nexport function test1(): [number, number] {\n return timeIt(() => {\n const REPEAT = 1000000000;\n let sum = 0;\n for (let i = 0; i < REPEAT; ++i) {\n sum += i;\n }\n });\n}\n\nexport async function bench(zone: napa.zone.Zone): Promise {\n zone.broadcast(timeIt.toString());\n zone.broadcast(test1.toString());\n\n // Warm up.\n test1();\n await zone.execute('', 'test1', []);\n\n // Actual test.\n let table = [];\n table.push([\"node time\", \"napa time\"]);\n let nodeTime = formatTimeDiff(test1());\n let napaTime = formatTimeDiff((await zone.execute('', 'test1', [])).value);\n table.push([nodeTime, napaTime]);\n \n console.log(\"## Node vs Napa JavaScript execution performance\\n\");\n console.log(mdTable(table));\n console.log('');\n}"
},
{
"path": "benchmark/store-overhead.ts",
"content": "// Copyright (c) Microsoft Corporation. All rights reserved.\n// Licensed under the MIT license.\n\nimport * as napa from '../lib/index';\nimport * as assert from 'assert';\nimport * as mdTable from 'markdown-table';\nimport { generateObject, formatTimeDiff } from './bench-utils';\n\ntype BenchmarkSettings = [\n string, // label\n number, // # of keys per level\n number, // # of levels\n string, // value type\n number // value length for string.\n];\n\nexport function bench() {\n console.log(\"Benchmarking store overhead...\");\n let settings: BenchmarkSettings[] = [\n // Number\n [\"1 level - 1 integers\", 1, 1, \"number\", 0],\n [\"1 level - 10 integers\", 10, 1, \"number\", 0],\n [\"1 level - 100 integers\", 100, 1, \"number\", 0],\n [\"10 level - 2 integers\", 2, 10, \"number\", 0],\n [\"2 level - 10 integers\", 10, 2, \"number\", 0],\n [\"3 level - 5 integers\", 5, 3, \"number\", 0],\n\n // String\n [\"1 level - 10 strings - length 10\", 10, 1, \"string\", 10],\n [\"1 level - 100 strings - length 10\", 100, 1, \"string\", 10],\n [\"2 level - 10 strings - length 10\", 10, 2, \"string\", 10],\n [\"3 level - 5 strings - length 10\", 5, 3, \"string\", 10],\n\n [\"1 level - 10 strings - length 100\", 10, 1, \"string\", 100],\n [\"1 level - 100 strings - length 100\", 100, 1, \"string\", 100],\n [\"2 level - 10 strings - length 100\", 10, 2, \"string\", 100],\n [\"3 level - 5 integers\", 5, 3, \"string\", 100],\n\n // Boolean\n [\"1 level - 10 booleans\", 10, 1, \"boolean\", 0],\n [\"1 level - 100 booleans\", 100, 1, \"boolean\", 0],\n [\"2 level - 10 booleans\", 10, 2, \"boolean\", 0],\n [\"3 level - 5 booleans\", 5, 3, \"boolean\", 0],\n ];\n\n let store = napa.store.create('store');\n let table = [];\n table.push([\"payload type\", \"size\", \"transport.marshall (ms)\", \"store.save (ms)\", \"transport.unmarshall (ms)\", \"store.get (ms)\"]);\n\n for (let s of settings) {\n const REPEAT = 1000;\n let object = generateObject(s[1], s[2], s[3], s[4])\n let payload = JSON.stringify(object);\n let size = payload.length;\n\n // transport.marshall\n let start = process.hrtime();\n for (let i = 0; i < REPEAT; ++i) {\n napa.transport.marshall(object, null);\n }\n let marshallTime = formatTimeDiff(process.hrtime(start));\n\n // store.set\n start = process.hrtime();\n for (let i = 0; i < REPEAT; ++i) {\n store.set('key', object);\n }\n let storeSetTime = formatTimeDiff(process.hrtime(start));\n\n assert.deepEqual(object, store.get('key'));\n\n // transport.unmarshall\n start = process.hrtime();\n for (let i = 0; i < REPEAT; ++i) {\n napa.transport.unmarshall(payload, null);\n }\n let unmarshallTime = formatTimeDiff(process.hrtime(start));\n\n // store.get\n start = process.hrtime();\n for (let i = 0; i < REPEAT; ++i) {\n store.get('key');\n }\n let storeGetTime = formatTimeDiff(process.hrtime(start));\n\n table.push([s[0], size, marshallTime, storeSetTime, unmarshallTime, storeGetTime]);\n }\n console.log(\"## Store access overhead\\n\");\n console.log(mdTable(table));\n console.log('');\n}"
},
{
"path": "benchmark/transport-overhead.ts",
"content": "// Copyright (c) Microsoft Corporation. All rights reserved.\n// Licensed under the MIT license.\n\nimport * as napa from '../lib/index';\nimport * as assert from 'assert';\nimport * as mdTable from 'markdown-table';\nimport { generateObject, timeDiffInMs, formatTimeDiff, formatRatio } from './bench-utils';\n\ntype BenchmarkSettings = [\n string, // label\n number, // # of keys per level\n number, // # of levels\n string, // value type\n number // value length for string.\n];\n\nexport function bench() {\n console.log(\"Benchmarking transport overhead...\");\n let settings: BenchmarkSettings[] = [\n // Number\n [\"1 level - 10 integers\", 10, 1, \"number\", 0],\n [\"1 level - 100 integers\", 100, 1, \"number\", 0],\n [\"10 level - 2 integers\", 2, 10, \"number\", 0],\n [\"2 level - 10 integers\", 10, 2, \"number\", 0],\n [\"3 level - 5 integers\", 5, 3, \"number\", 0],\n\n // String\n [\"1 level - 10 strings - length 10\", 10, 1, \"string\", 10],\n [\"1 level - 100 strings - length 10\", 100, 1, \"string\", 10],\n [\"2 level - 10 strings - length 10\", 10, 2, \"string\", 10],\n [\"3 level - 5 strings - length 10\", 5, 3, \"string\", 10],\n\n [\"1 level - 10 strings - length 100\", 10, 1, \"string\", 100],\n [\"1 level - 100 strings - length 100\", 100, 1, \"string\", 100],\n [\"2 level - 10 strings - length 100\", 10, 2, \"string\", 100],\n [\"3 level - 5 integers\", 5, 3, \"string\", 100],\n\n // Boolean\n [\"1 level - 10 booleans\", 10, 1, \"boolean\", 0],\n [\"1 level - 100 booleans\", 100, 1, \"boolean\", 0],\n [\"2 level - 10 booleans\", 10, 2, \"boolean\", 0],\n [\"3 level - 5 booleans\", 5, 3, \"boolean\", 0],\n ];\n\n let table = [];\n table.push([\"payload type\", \"size\", \"JSON.stringify (ms)\", \"transport.marshall (ms)\", \"JSON.parse (ms)\", \"transport.unmarshall (ms)\"]);\n for (let s of settings) {\n const REPEAT = 1000;\n let object = generateObject(s[1], s[2], s[3], s[4])\n let payload = JSON.stringify(object);\n let size = payload.length;\n\n // JSON.stringify\n let start = process.hrtime();\n for (let i = 0; i < REPEAT; ++i) {\n JSON.stringify(object);\n }\n let stringifyTime = timeDiffInMs(process.hrtime(start));\n let stringifyTimeText = formatTimeDiff(stringifyTime);\n\n // transport.marshall\n start = process.hrtime();\n for (let i = 0; i < REPEAT; ++i) {\n napa.transport.marshall(object, null);\n }\n let marshallTime = timeDiffInMs(process.hrtime(start));\n let marshallTimeText = formatTimeDiff(marshallTime) + \" \" + formatRatio(marshallTime, stringifyTime);\n\n let marshalled = napa.transport.marshall(object, null);\n assert.deepEqual(payload, marshalled);\n\n // JSON.parse\n start = process.hrtime();\n for (let i = 0; i < REPEAT; ++i) {\n JSON.parse(payload);\n }\n let parseTime = timeDiffInMs(process.hrtime(start));\n let parseTimeText = formatTimeDiff(parseTime);\n\n start = process.hrtime();\n for (let i = 0; i < REPEAT; ++i) {\n napa.transport.unmarshall(payload, null);\n }\n let unmarshallTime = timeDiffInMs(process.hrtime(start));\n let unmarshallTimeText = formatTimeDiff(unmarshallTime) + \" \" + formatRatio(unmarshallTime, parseTime);\n\n table.push([s[0], size, stringifyTimeText, marshallTimeText, parseTimeText, unmarshallTimeText]);\n }\n console.log(\"## Transport overhead\\n\");\n console.log(mdTable(table));\n console.log('');\n}"
},
{
"path": "benchmark/tsconfig.json",
"content": "{\n \"compilerOptions\": {\n \"module\": \"commonjs\",\n \"target\": \"es5\",\n \"experimentalDecorators\": true,\n \"noImplicitAny\": false,\n \"declaration\": false,\n \"sourceMap\": false,\n \"lib\": [\"es2015\"]\n }\n}"
},
{
"path": "build.bat",
"content": ":: Copyright (c) Microsoft Corporation. All rights reserved.\n:: Licensed under the MIT license.\n@echo off\n\nset NODE_EXE=%~dp0\\node.exe\nif not exist \"%NODE_EXE%\" (\n set NODE_EXE=node\n)\n\n%NODE_EXE% %~dp0\\build.js %*\n"
},
{
"path": "build.js",
"content": "// Copyright (c) Microsoft Corporation. All rights reserved.\n// Licensed under the MIT license.\n\n// Distinguish between running this file as a script or loading it as a module.\nif (module.parent) {\n // Loaded as a module - 'require('./build.js')\n exports.paths = require('./scripts/paths');\n}\nelse {\n // Loaded as a script - 'node build.js'\n\n // Remove first two parameters which are node executable and this javascript file.\n // Transform all parameters to lowercase for easier handling.\n let params = process.argv.slice(2).map((item) => item.toLowerCase());\n\n // Specify wheater cleanup is needed.\n if (params.indexOf('clean') != -1) {\n require('./scripts/clean').clean();\n }\n \n // Only build if embed was specified as a parameter.\n if (params.indexOf('embed') != -1) {\n let embedded = require('./scripts/embedded');\n\n if (params.indexOf('debug') != -1) {\n embedded.build('debug');\n }\n else {\n embedded.build('release');\n }\n }\n}\n"
},
{
"path": "docs/api/index.md",
"content": "# API References\n\n## Core modules\n- Napa.js specific [`global`](./napa-globals.md) variables\n- Namespace [`zone`](./zone.md): Multi-thread JavaScript runtime\n- Namespace [`transport`](./transport.md): Passing JavaScript values across threads\n- Namespace [`store`](./store.md): Sharing JavaScript values by global storage\n- Namespace [`sync`](./sync.md): Handling synchronization between threads\n- Namespace [`memory`](./memory.md): Handling native objects and memory\n- Namespace [`metric`](./metric.md): Pluggable metrics.\n- Function [`log`](./log.md): Pluggable logging.\n\n## Node compatibility\n- [List of supported Node APIs](./node-api.md)\n\n## API for creating modules\n- [Writing Napa.js modules](./module.md)\n"
},
{
"path": "docs/api/log.md",
"content": "# Function `log`\n\n## Table of Contents\n- [Introduction](#intro)\n- [C++ API](#cpp-api)\n- [JavaScript API](#js-api)\n - [`log(message: string): void`](#log)\n - [`log(section: string, message: string): void`](#log-with-section)\n - [`log(section: string, traceId: string, message: string): void`](#log-with-traceid)\n - [`log.err(...)`](#log-err)\n - [`log.warn(...)`](#log-warn)\n - [`log.info(...)`](#log-info)\n - [`log.debug(...)`](#log-debug)\n- [Using custom logging providers](#use-custom-providers)\n- [Developing custom logging providers](#develop-custom-providers)\n\n## Introduction\nLogging is a basic requirement for building services. `napajs` logging API enables developers to integrate their own logging capabilities in both JavaScript and C++ (addon) world.\n\nA log row may contain the following information:\n- (Optional) Section: Useful field to filter log rows. Treatment is defined by logging providers.\n- (Optional) Trace ID: Useful field to join logs in the same transaction or request.\n- (Required) Message: Log message.\n- (Required) Logging level: \n - Error: for application error.\n - Warn: for warning information.\n - Info: for notification. \n - Debug: for debugging purpose.\n\n## C++ API\nInclude header: ``\n\nMacros:\n- LOG_ERROR(section, format, ...)\n- LOG_ERROR_WITH_TRACEID(section, traceId, format, ...)\n- LOG_WARNING(section, format, ...)\n- LOG_WARNING_WITH_TRACEID(section, traceId, format, ...)\n- LOG_INFO(section, format, ...)\n- LOG_INFO_WITH_TRACEID(section, traceId, format, ...)\n- LOG_DEBUG(section, format, ...)\n- LOG_DEBUG_WITH_TRACEID(section, traceId, format, ...)\n\n```cpp\n#include \n\nvoid MyFunction() {\n // ...\n LOG_ERROR(\"init\", \"error: %s\", errorMessage.c_str());\n}\n```\n\n## JavaScript API\n\n### log(message: string): void\nIt logs a message. Using info level. \n\n* A `log` is a shortcut for `log.info`.*\n\nExample:\n```js\nvar napa = require('napajs');\nnapa.log('program started');\n```\n\n### log(section: string, message: string): void\nIt logs a message with a section. Using info level. \n\nExample:\n```js\nnapa.log('init', 'program started');\n```\n\n### log(section: string, traceId: string, message: string): void\nIt logs a message with a section, associating it with a traceId. Using info level.\n\nExample:\n```js\nnapa.log('request', 'A1B2C3D4', 'request received');\n```\n### log.err(...)\nIt logs an error message. Three variations of arguments are the same with the `log`.\n\n### log.warn(...)\nIt logs a warning message. Three variations of arguments are the same with the `log`.\n\n### log.info(...)\nIt logs an info message. Three variations of arguments are the same with the `log`.\n\n### log.debug(...)\nIt logs a debug message. Three combinations of arguments are the same with the `log`.\n\n## Using custom logging providers\nDevelopers can hook up custom logging provider by calling the following before creation of any zones:\n```js\nnapa.runtime.setPlatformSettings({\n \"loggingProvider\": \"\"\n}\n```\n## Developing custom logging providers\nTBD\n"
},
{
"path": "docs/api/memory.md",
"content": "# Namespace `memory`\n\n## Table of Contents\n- [API](#api)\n - Type [`Handle`](#handle)\n - Interface [`Shareable`](#shareable)\n - Interface [`Allocator`](#allocator)\n - [`allocator.allocate(size: number): Handle`](#allocator-allocate)\n - [`allocator.deallocate(handle: Handle, sizeHint: number): void`](#allocator-deallocate)\n - [`allocator.type: string`](#allocator-type)\n - Interface [`AllocatorDebugger`](#allocatordebugger)\n - [`allocatorDebugger.getDebugInfo(): string`](#allocatordebugger-getdebuginfo)\n - Function [`debugAllocator(allocator: Allocator): AllocatorDebugger`](#debugallocator)\n - Object [`crtAllocator`](#crtallocator)\n - Object [`defaultAllocator`](#defaultallocator)\n - [Memory allocation in C++ addon](#memory-allocation-in-cpp-addon)\n\n## API\n## Type `Handle`\nHandle is defined in TypeScript as below:\n```ts\ntype Handle = [number, number]\n``` \nIt is a standard way to represent a 64-bit pointer in Napa.\n\n## Interface `Shareable`\nInterface for native object wrap that can be shared across multiple JavaScript threads.\n\n## Interface `Allocator`\nInterface for memory allocator that allocates memory for native objects. \n\n### allocator.allocate(size: number): Handle\nIt allocates memory of requested size.\n\n```js\nvar handle = allocator.allocate(10);\n```\n### allocator.deallocate(handle: Handle, sizeHint: number): void\nIt deallocates memory from a input handle, with a size hint which is helpful for some C++ allocator implementations for deallocating memory.\n```js\nallocator.deallocate(handle, 10);\n```\n### allocator.type: string\nIt gets a string type identifier for the allocator, which will be useful during debugging purpose.\n\n## Interface `AllocatorDebugger`\n`AllocatorDebugger` extends interface `Allocator`, with a member function `getDebugInfo` to expose debug information. Basically an allocator debugger will use a pass-in allocator for memory allocation, meanwhile intercepting it to keep track of allocation count and size. \n\n### allocatorDebugger.getDebugInfo(): string\nIt gets the debug information for allocation. Implementations of interface `AllocatorDebugger` can have different schema on debug info.\n\n## debugAllocator(allocator: Allocator): AllocatorDebugger\nIt returns a simple allocator debugger, which returns debug information like below:\n```json\n{\n \"allocate\": 10,\n \"allocateSize\": 1024,\n \"deallocate\": 8,\n \"deallocateSize\": 912\n}\n```\n## Object `crtAllocator`\nIt returns a C-runtime allocator from Napa.js shared library. Its corresponding C++ part is `napa::memory::GetCrtAllocator()`.\n\n## Object `defaultAllocator`\nIt returns the default allocator from Napa.js shared library. Its corresponding C++ part is `napa::memory::GetDefaultAllocator()`. \n\nUsers can set default allocation/deallocation callback in `napa_allocator_set` API.\n\n## Memory allocation in C++ addon\nMemory allocation in C++ addon is tricky. A common pitfall is to allocate memory in one dll, but deallocate in another. This can cause issue if C-runtime in these 2 dlls are not compiled the same way. \n\nThere are also advanced scenarios that user want to customize memory allocation. Napa.js provides APIs for customizing memory allocator as well.\n\n### Recommended way of allocate memory\nTBD\n\n### Customize memory allocation\nTBD\n\n"
},
{
"path": "docs/api/metric.md",
"content": "# Namespace `metric`\n\n## Table of Contents\n- [Introduction](#intro)\n- [C++ API](#cpp-api)\n - Interface [`Metric`](#cpp-metric)\n - Interface [`MetricProvider`](#cpp-metricprovider)\n - Function [`MetricProvider& GetMetricProvider()`](#cpp-getmetricprovider)\n- [JavaScript API](#js-api)\n - Enum [`MetricType`](#metrictype)\n - Class [`Metric`](#metric)\n - [`set(value: number, dimensions?: string[]): void`](#metric-set)\n - [`increment(dimensions?: string[]): void`](#metric-increment);\n - [`decrement(dimensions?: string[]): void`](#metric-decrement);\n - Function [`get(section: string, name: string, type: MetricType, dimensionNames: string[])`](#get)\n- [Using custom metric providers](#use-custom-providers)\n- [Developing custom metric providers](#develop-custom-providers)\n\n## Introduction\nSimilar as logging, metric is a basic requirement for creating monitorable services. Metric API enables developers to use their own metric system in both JavaScript and C++ (addon) world.\n\nA metric has its identity containing following information:\n- **Section**: The group or category of the metric.\n- **Name**: Name of the metric. Section/Name combination should be unique in the system.\n- **Type**: Type of the metric, which can be\n - *Number*: An absolute number, e.g: PrivateBytes.\n - *Rate*: A flowing volume in number, e.g: QueryPerSecond.\n - *Percentile*: An absolute number that needs to be sampled by percentiles, e.g: SuccessLatency.\n- **Dimensions**: A metric can have multiple dimensions, each dimension can bind with a string value at runtime. e.g: IncomingRequestRate can have 2 dimensions: ['client-id', 'request-type'].\n\nMetrics are process-wise objects, which can be used across [zones](./zone.md#intro).\n\n## C++ API\n### Interface Metric\n```cpp\n /// Enumeration of metric type. \n enum class MetricType {\n Number = 0,\n Rate,\n Percentile,\n };\n\n /// Interface to represent a multi-dimensional metric with a maximum dimensionality of 64. \n class Metric {\n public:\n\n /// Sets a metric value with variadic dimension arguments. \n /// Int64 value. \n /// Number of dimensions being set. \n /// Array of dimension value names. \n /// Success/Fail. \n /// \n /// The number of dimension values must exactly match the number of dimensions provided when\n /// creating this metric.\n /// \n virtual bool Set(int64_t value, size_t numberOfDimensions, const char* dimensionValues[]) = 0;\n\n /// \n /// Increments a metric value with variadic dimension arguments.\n /// Use mainly to simplify rate counters.\n /// \n /// UInt64 value to increment. \n /// Number of dimensions being set. \n /// Array of dimension value names. \n /// Success/Fail. \n /// \n /// The number of dimension values must exactly match the number of dimensions\n /// provided when creating this metric.\n /// \n virtual bool Increment(uint64_t value, size_t numberOfDimensions, const char* dimensionValues[]) = 0;\n\n /// \n /// Decrements metric value with variadic dimension arguments.\n /// Use mainly to simplify rate counters.\n /// \n /// UInt64 value to decrement. \n /// Number of dimensions being set. \n /// Array of dimension value names. \n /// Success/Fail. \n /// \n /// The number of dimension values must exactly match the number of dimensions\n /// provided when creating this metric.\n /// \n virtual bool Decrement(uint64_t value, size_t numberOfDimensions, const char* dimensionValues[]) = 0;\n\n /// Explicitly destroys the Metric. \n /// \n /// Consumers are not required to call this.\n /// The MetricProvider owns this class and will automatically perform cleanup on shutdown.\n /// \n virtual void Destroy() = 0;\n\n protected:\n\n /// Prevent calling delete on the interface. Must use Destroy! \n virtual ~Metric() = default;\n };\n```\n### Interface MetricProvider\n```cpp\n\n /// Interface for a generic metric provider. \n /// \n /// Ownership of this metric provider belongs to the shared library which created it. Hence the explicit\n /// Destroy method in this class. To simplify memory management across multiple shared libraries, this class\n /// can only be created via a factory method provided by the shared library. When it is no longer needed,\n /// the caller may call Destroy() which will tell the shared library which created it to dispose of the object.\n /// \n class MetricProvider {\n public:\n\n /// \n /// Gets or creates a N-dimensional metric. Metric objects are owned and cached by this class.\n /// Up to 64 dimensions may be used.\n /// Section of the metric.\n /// Name of the metric.\n /// Type of the metric.\n /// \n /// Number of dimensions requested for this metric.\n /// Represents the size of the array passed in for p_dimensionNames.\n /// \n /// Array of dimension names being requested for this metric.\n /// \n /// The IMetric class returned is owned and cached by this class.\n /// Callers are not required to call destroy() on the Metric.\n /// \n virtual Metric* GetMetric(\n const char* section,\n const char* name,\n MetricType type,\n size_t dimensions,\n const char* dimensionNames[]) = 0;\n\n /// Explicitly destroys the metric provider. \n virtual void Destroy() = 0;\n\n protected:\n\n /// Prevent calling delete on the interface. Must use Destroy! \n virtual ~MetricProvider() = default;\n };\n```\n### function `MetricProvider& GetMetricProvider()`\n```cpp\n/// Exports a getter function for retrieves the configured metric provider. \nNAPA_API MetricProvider& GetMetricProvider();\n```\n## JavaScript API\n\n### enum `MetricType`\n```ts\nexport enum MetricType {\n Number = 0,\n Rate,\n Percentile,\n}\n```\n### Class `Metric`\n\nClass to manipulate metrics in JavaScript.\n\n### `set(value: number, dimensions?: string[]): void`\n\nSet absolute value on an instance of the metric constrained by dimension values.\nExample:\n```js\n// Create a percentile metric to measure end-to-end latency, with 1 dimension of client-id.\nlatency = napa.metric.get(\n 'app1',\n 'end-to-end-latency',\n napa.metric.MetricType.Percentile, \n ['client-id']);\n\n// Set end-to-end latency of current request to 100, with client-id 'client1'.\nlatency.set(100, ['client1']);\n```\n\n#### `increment(dimensions?: string[]): void`\n\nIncrement the value of an instance of the metric constrained by dimension values.\n\nExample:\n```js\n// Create a percentile metric to measure end-to-end latency, with 1 dimension of client-id.\nlatency = napa.metric.get(\n 'app1',\n 'qps',\n napa.metric.MetricType.Rate, \n ['client-id']);\n\n// Increment QPS of client-id 'client1'.\nlatency.increment(['client1']);\n```\n#### `decrement(dimensions?: string[]): void`\nDecrement the value of an instance of the metric constrained by dimension values.\n\n### function `get(section: string, name: string, type: MetricType, dimensions: string[] = []): Metric`\nCreate a metric with an identity consisting of section, name, type and dimensions. If a metric already exists with given parameters, returns existing one.\n\nExample:\n```ts\nimport * as napa from 'napajs';\nlet metric = napa.metric.get(\n 'app1', \n 'counter1', \n napa.metric.MetricType.Number, \n []);\nmetric.increment([]);\n```\n## Using custom metric providers\nDevelopers can hook up custom metric provider by calling the following before creation of any zones:\n```ts\nnapa.runtime.setPlatformSettings({\n \"metricProvider\": \"\"\n}\n```\n## Developing custom metric providers\nTBD\n"
},
{
"path": "docs/api/module.md",
"content": "# Napa.js Module\n\n## Table of Contents\n- [Introduction](#intro)\n- [Developing modules](#develop-modules)\n - [Module: JavaScript vs C++](#js-vs-cpp)\n- [Quick reference](#quick-ref)\n - [JavaScript module](#ref-js-module)\n - [C++ module](#ref-cpp-module)\n- [API](#api)\n - [JavaScript API](#js-api)\n - [C++ API](#cpp-api)\n - [Exporting JavaScript class from C++ modules](#export-class)\n - [V8 helpers](#v8helpers)\n - [Using STL with custom allocators](#stl-with-allocator)\n- [Special topics](#topics)\n - [Topic #1: Make objects shareable across multiple JavaScript threads](#topic-shareable-objects)\n - [Topic #2: Asynchronous functions](#topic-async-functions)\n - [Topic #3: Memory management in C++ modules](#topic-memory-management)\n\n## Introduction\nNapa.js follows [Node.js' convention](https://nodejs.org/api/modules.html) to support modules, that means:\n\n1) Both JavaScript modules and C++ modules are supported.\n2) Module resolution follows the [same algorithm](https://nodejs.org/api/modules.html#modules_all_together), except instead of searching file extension `.node` for addons, Napa.JS searches `.napa`.\n3) Supports NPM, with the [same way](https://docs.npmjs.com/getting-started/creating-node-modules) to create and publish modules.\n4) API of creating C++ modules (addons) are similar. Napa.JS introduced macros that the same source code can be compiled to produce both Napa.js addon and Node.js addon.\n\nBut there are also differences:\n1) C++ module that is designed/implemented for Napa.js can run on Node.JS (need different compile flags to produce '.napa' and '.node'). But not vice versa.\n2) Napa.js doesn't support all Node.js API. Node API are supported [incrementally](./node-api.md) on the motivation of adding Node.js built-ins and core modules that are needed for computation heavy tasks. You can access full capabilities of Node exposed via [Node zone](./zone.md#node-zone).\n3) Napa.js doesn't provide `uv` functionalities, thus built-ins and core modules have its own implementation. To write async function in addon, methods `DoAsyncWork`/`PostAsyncWork` are introduced to work for both Napa.js and Node.js.\n4) Napa.js supports embed mode. C++ modules need separate compilation between Node mode and embed mode.\n\n\n## Developing modules\n### Module: JavaScript vs. C++\nA quick glance at NPM will reveal that most modules are pure JavaScript. These are only a few reasons that you may want to create a C++ module.\n- You want to expose JavaScript API for existing C/C++ functionalities.\n- Code includes considerably amount of computation that is performance critical.\n- Objects need to be shared across multiple JavaScript threads, marshalling/unmarshalling cost on these objects is not trivial (big payload size, complex structure, etc.), but it's reasonable cheap to expose JavaScript APIs from underlying native objects.\n- In embed mode, you want to communicate with host process with native objects.\n\n[This post](https://docs.npmjs.com/getting-started/creating-node-modules) gives a good introduction on creating a JavaScript module. For creating a Napa.JS C++ module, please refer to the [API](#api) section or checkout examples in the [quick reference](#quick-reference) section.\n\n## Quick reference\n\n### JavaScript module\n\n| Description | Transportable | Example code |\n| ------------------------------------------------------------ | ------------- | ------------ |\n| Standard JavaScript module | | [Blog post](https://www.hacksparrow.com/how-to-write-node-js-modules.html) |\n| Share JavaScript object across isolates | X | |\n\n### C++ module\n\n| Description | ObjectWrap | Transportable | Async function | Example code |\n| ------------------------------------------------------------ | ---------- | ------------- | -------------- | ------------ |\n| Export JavaScript function only | | | | hello-world [[.md](../../examples/modules/hello-world/README.md) [.cpp](../../examples/modules/hello-world/node/addon.cpp) [test](../../examples/modules/hello-world/test/test.ts)] |\n| Export JavaScript object (ObjectWrap) | X | | | plus-number [[.md](../../examples/modules/plus-number/README.md) [.cpp](../../examples/modules/plus-number/node/addon.cpp) [test](../../examples/modules/plus-number/test/module-test/test.ts)] |\n| Share C++ object across isolates | X | X | | allocator-wrap [[.h](../../src/module/core-modules/napa/allocator-wrap.h) [.cpp](../../src/module/core-modules/napa/allocator-wrap.cpp)] |\n| Export asynchronous JavaScript function | X | | X | async-number [[.md](../../examples/modules/async-number/README.md) [.cpp](../../examples/modules/async-number/node/addon.cpp) [test](../../examples/modules/async-number/test/test.ts)] |\n\n## API\n### JavaScript\nSee [API reference](./index.md).\n\n### C++\n#### Exporting JavaScript classes from C++ modules\nTBD\n#### V8 helpers\nTBD\n#### Using STL with custom allocators\nTBD\n\n## Special topics\n### Topic #1: Make objects shareable across multiple JavaScript threads\nTBD\n\n### Topic #2: Asynchronous functions\nTBD\n\n### Topic #3: Memory management in C++ modules\nTBD\n"
},
{
"path": "docs/api/napa-globals.md",
"content": "# Napa.js specific global variables\n\nThis file describes Napa.js specific globals, please refer to [this documentation](./node-api.md#globals) for Node.js globals.\n\n## `global.napa`\nShortcut to access `napajs` module in all Napa enabled isolates. This is helpful to avoid extra `require` when using `napajs` module in anonymous function during `broadcast` or `execute`.\n\nExample:\n```js\nvar napa = require('napajs');\n\nvar zone = napa.zone.create('zone1');\n\nfunction test() {\n global.napa.log('hi');\n}\n\nzone.execute(test);\n\n```"
},
{
"path": "docs/api/node-api.md",
"content": "# Node.js Compatibility\n\nNapa.js doesn't support full compatibility with node.js and necessary core modules will be added incrementally. Here are the list of what Napa.js currently supports. Please refer to https://nodejs.org/api/all.html for details.\n\n## Assert\n\nSince Napa doesn't support *Buffer* yet, assert is not working on *Buffer*.\n\n* assert(value[, message])\n* assert.deepEqual(actual, expected[, message])\n* assert.doesNotThrow(block[, error][, message])\n* assert.equal(actual, expected[, message])\n* assert.fail(actual, expected, message, operator)\n* assert.ifError(value)\n* assert.notDeepEqual(actual, expected[, message])\n* assert.notEqual(actual, expected[, message])\n* assert.notStrictEqual(actual, expected[, message])\n* assert.ok(value[, message])\n* assert.strictEqual(actual, expected[, message])\n* assert.throws(block[, error][, message])\n\n## Console\n\n* console.log([data][, ...args])\n\n## Events\n\n* Event: 'newListener'\n* Event: 'removeListener'\n* EventEmitter.listenerCount(emitter, eventName)\n* EventEmitter.defaultMaxListeners\n* emitter.addListener(eventName, listener)\n* emitter.emit(eventName[, ...args])\n* emitter.eventNames()\n* emitter.getMaxListeners()\n* emitter.listenerCount(eventName)\n* emitter.listeners(eventName)\n* emitter.on(eventName, listener)\n* emitter.once(eventName, listener)\n* emitter.prependListener(eventName, listener)\n* emitter.prependOnceListener(eventName, listener)\n* emitter.removeAllListeners([eventName])\n* emitter.removeListener(eventName, listener)\n* emitter.setMaxListeners(n)\n\n## File system\n\n* fs.readFileSync(path)\n* fs.writeFileSync(file, data)\n* fs.mkdirSync(path)\n* fs.existsSync(path)\n* fs.readdirSync(path)\n\n## Globals\n\n* __dirname\n* __filename\n* console\n* exports\n* global\n* module\n * module.exports\n * module.id\n* process\n* require\n\n## OS\n\n* os.type\n\n## Path\n\n* path.basename(path[, ext])\n* path.dirname(path)\n* path.extname(path)\n* path.format(pathObject)\n* path.isAbsolute(path)\n* path.join([...paths])\n* path.normalize(path)\n* path.relative(from, to)\n* path.resolve([...paths])\n* path.sep\n\n## Process\n\n* process.argv\n* process.cwd()\n* process.chdir(directory)\n* process.env\n* process.execPath\n* process.exit(code)\n* process.hrtime([time])\n* process.pid\n* process.platform\n* process.umask([mask])\n\n## TTY\n\n* tty.isatty(fd)\n\n## Util\n\n* util.debuglog(section)\n* util.format(format[, ...args])\n* util.inherits(constructor, superConstructor)\n* util.inspect(object[, options])\n* util._extend(target, source)\n"
},
{
"path": "docs/api/store.md",
"content": "# Namespace `store`\n\n## Table of Contents\n- [Introduction](#intro)\n- [API](#api)\n - [`create(id: string): Store`](#create)\n - [`get(id: string): Store`](#get)\n - [`getOrCreate(id: string): Store`](#getorcreate)\n - [`count: number`](#count)\n - Interface [`Store`](#store)\n - [`store.id: string`](#store-id)\n - [`store.set(key: string, value: any): void`](#store-set)\n - [`store.get(key: string): any`](#store-get)\n - [`store.has(key: string): boolean`](#store-has)\n - [`store.size: number`](#store-size)\n\n## Introduction\nStore API is a necessary complement of sharing [transportable](transport.md#transportable-types) objects across JavaScript threads, on top of passing objects via arguments. During [`store.set`](#store-set), values marshalled into JSON and stored in process heap, so all threads can access it, and unmarshalled while users retrieve them via [`store.get`](#store-get).\n\nThough very convenient, it's not recommended to use store to pass values within a transaction or request, since its overhead is more than passing objects by arguments (there are extra locking, etc.). Besides, developers have the obligation to delete the key after usage, while it's automatically managed by reference counting in passing arguments.\n\n## API\nFollowing APIs are exposed to create, get and operate upon stores.\n\n### create(id: string): Store\nIt creates a store by a string identifier that can be used to get the store later. When all references to the store from all JavaScript VMs are cleared, the store will be destroyed. Thus always keep a reference at global or module scope is usually a good practice using `Store`. Error will be thrown if the id already exists.\n\nExample:\n```js\nvar store = napa.store.create('store1');\n```\n### get(id: string): Store\nIt gets a reference of store by a string identifier. `undefined` will be returned if the id doesn't exist. \n\nExample:\n```js\nvar store = napa.store.get('store1');\n```\n\n### getOrCreate(id: string): Store\nIt gets a reference of store by a string identifier, or creates it if the id doesn't exist. This API is handy when you want to create a store in code that is executed by every worker of a zone, since it doesn't break symmetry.\n\nExample:\n```js\nvar store = napa.store.getOrCreate('store1');\n```\n### count: number\nIt returns count of living stores.\n\n### Interface `Store`\nInterface that let user to put and get objects across multiple JavaScript VMs.\n\n### store.id: string\nIt gets the string identifier for the store.\n\n### store.set(key: string, value: any): void\nIt puts a [transportable](transport.md#transportable-types) value into store with a string key. If key already exists, new value will override existing value.\n\nExample:\n```js\nstore.set('status', 1);\n```\n### store.get(key: string): any\nIt gets a [transportable](transportable.md#transportable-types) value from the store by a string key. If key doesn't exist, `undefined` will be returned.\n\nExample:\n```js\nvar value = store.get('status');\nassert(value === 1);\n```\n### store.has(key: string): boolean\nIt tells if a key exists in current store.\n\nExample:\n```js\nassert(store.has('status'))\n```\n\n### store.size: number\nIt tells how many keys are stored in current store.\n"
},
{
"path": "docs/api/sync.md",
"content": "# Namespace `sync`\n## Table of Contents\n- class [`Lock`](#interface-lock)\n - [`lock.guardSync(func: (...params: any[]) => any, params?: any[]): any`](#lock-guard-sync-func-any-any)\n\n\n\n## APIs\nNamespace `sync` deal with synchronization between threads in Napa. `Lock` is provided for exclusive and shared mutex scenarios.\n## Interface `Lock`\nExclusive Lock, which is [transportable](transport.md#transportable) across JavaScript threads.\n\nUse `napa.sync.createLock()` to create a lock.\n```ts\nvar lock = napa.sync.createLock();\n```\n### lock.guardSync(func: (...params: any[]) => any, params?: any[]): any\nRun input function synchronously and obtain the lock during its execution, returns what the function returns, or throws error if input function throws. Lock will be released once execution finishes.\n```ts\ntry {\n var value = lock.guardSync(() => {\n // DoSomething may throw.\n return DoSomething();\n });\n console.log(value);\n}\ncatch(error) {\n console.log(error);\n}\n```\n\nAn example [Synchronized Loading](./../../examples/tutorial/synchronized-loading) demonstrated how to implement a shared, lazy-loading phone book.\n\n\n\n"
},
{
"path": "docs/api/transport.md",
"content": "# Namespace `transport`\n\n## Table of Contents\n- [Introduction](#intro)\n - [Transportable types](#transportable-types)\n - [Constructor ID](#constructor-id)\n - [Transport context](#transport-context)\n - [Transporting functions](#transporting-functions)\n - [Transporting JavaScript built-in objects](#transporting-built-in)\n- API\n - [`isTransportable(jsValue: any): boolean`](#istransportable)\n - [`register(transportableClass: new(...args: any[]) => any): void`](#register)\n - [`marshall(jsValue: any, context: TransportContext): string`](#marshall)\n - [`unmarshall(json: string, context: TransporteContext): any`](#unmarshall)\n - class [`TransportContext`](#transportcontext)\n - [`context.saveShared(object: memory.Shareable): void`](transportcontext-saveshared)\n - [`context.loadShared(handle: memory.Handle): memory.Shareable`](transportcontext-loadshared)\n - [`context.sharedCount: number`](transportcontext-sharedcount)\n - interface [`Transportable`](#transportable)\n - [`transportable.cid: string`](#transportable-cid)\n - [`transportable.marshall(context: TransportContext): object`](#transportable-marshall)\n - [`transportable.unmarshall(payload: object, context: TransportContext): void`](#transportable-unmarshall)\n - abstract class [`TransportableObject`](#transportableobject)\n - [`transportableObject.cid: string`](#transportableobject-cid)\n - [`transportableObject.marshall(context: TransportContext): object`](#transportableobject-marshall)\n - [`transportableObject.unmarshall(payload: object, context: TransportContext): void`](#transportableobject-unmarshall)\n - abstract [`transportableObject.save(payload: object, context: TransportContext): void`](#transportableobject-save)\n - abstract [`transportableObject.load(payload: object, context: TransportContext): void`](#transportableobject-load)\n - decorator [`cid`](#decorator-cid)\n\n## Introduction\nExisting JavaScript engines are not designed for running JavaScript across multiple VMs, which means every VM manages their own heap. Passing values from one VM to another has to be marshalled/unmarshalled. The size of payload and complexity of object will greatly impact communication efficiency. In Napa, we try to work out a design pattern for efficient object sharing, based on the fact that all JavaScript VMs (exposed as workers) reside in the same process, and native objects can be wrapped and exposed as JavaScripts objects.\n\nFollowing concepts are introduced to implement this pattern:\n\n### Transportable types\nTransportable types are JavaScript types that can be passed or shared transparently across Napa workers. They are used as value types for passing arguments in [`zone.broadcast`](zone.md#broadcast-function) / [`zone.execute`](zone.md#execute-anonymous-function), and sharing objects in key/value pairs via [`store.set`](store.md#store-set) / [`store.get`](store.md#store-get).\n\nTransportable types are:\n- JavaScript primitive types: undefined, null, boolean, number, string\n- Object (TypeScript class) that implement [`Transportable`](#transportable) interface\n- Function without referencing closures.\n- JavaScript standard built-in objects in this whitelist.\n * ArrayBuffer\n * Float32Array\n * Float64Array\n * Int16Array\n * Int32Array\n * Int8Array\n * SharedArrayBuffer\n * Uint16Array\n * Uint32Array\n * Uint8Array\n- Array or plain JavaScript object that is composite pattern of above.\n\n### Constructor ID (cid)\nFor user classes that implement the [`Transportable`](#transportable) interface, Napa uses Constructor ID (`cid`) to lookup constructors for creating a right object from a string payload. `cid` is marshalled as a part of the payload. During unmarshalling, the transport layer will extract the `cid`, create an object instance using the constructor associated with it, and then call unmarshall on the object. \n\nIt's the class developer's responsibility to choose the right `cid` for your class. To avoid conflict, we suggest to use the combination of module.id and class name as `cid`. Developer can use class decorator [`cid`](#decorator-cid) to register a user Transportable class automatically, when using TypeScript with decorator feature enabled. Or call [`transport.register`](#register) manually during module initialization.\n\n### Transport context\nThere are states that cannot be saved or loaded in serialized form (like std::shared_ptr), or it's very inefficient to serialize (like JavaScript function). Transport context is introduced to help in these scenarios. TransportContext objects can be passed from one JavaScript VM to another, or stored in the native world, so lifecycle of shared native objects extended by using TransportContext. An example of the `Transportable` implementation using TransportContext is [`ShareableWrap`](./../../inc/napa/module/shareable-wrap.h).\n\n### Transporting functions\nJavaScript function is a special transportable type, through marshalling its definition into a [store](./store.md#intro), and generate a new function from its definition on target thread. \n\nHighlights on transporting functions are:\n- For the same function, marshall/unmarshall is an one-time cost on each JavaScript thread. Once a function is transported for the first time, later transportation of the same function to previous JavaScript thread can be regarded as free.\n- Closure cannot be transported, but you won't get an error when transporting a function. Instead, you will get runtime error complaining a variable (from closure) is undefined when you can the function later.\n- `__dirname` / `__filename` can be accessed in transported function, which is determined by `origin` property of the function. By default, `origin` property is set to the current working directory.\n\n### Transporting JavaScript built-in objects\nJavaScript standard built-in objects in [the whitelist](#built-in-whitelist) can be transported among napa workers transparently. JavaScript Objects with properties in these types are also able to be transported. Please refer to [unit tests](./../../test/transport-test.ts) for detail.\n\nAn example [Parallel Quick Sort](./../../examples/tutorial/parallel-quick-sort) demonstrated transporting TypedArray (created from SharedArrayBuffer) among multiple Napa workers for efficient data sharing.\n\n## API\n\n### isTransportable(jsValue: any): boolean\nIt tells whether a JavaScript value is transportable or not.\n```ts\n// JS primitives\nassert(transport.isTransportable(undefined));\nassert(transport.isTransportable(null));\nassert(transport.isTransportable(1));\nassert(transport.isTransportable('string'));\nassert(transport.isTransportable(true));\n\n// Transportable addon\nassert(transport.isTransportable(napa.memory.crtAllocator));\n\n// Composite of transportable types.\nassert(transport.isTransportable([\n 1, \n \"string\", \n { a: napa.memory.crtAllocator }\n ]));\n\nclass B {\n field1: number;\n field2: string;\n}\n\n// Not transportable JS class. (not registered with @cid).\nassert(!transport.isTransportable(new B()));\n```\n### register(transportableClass: new(...args: any[]) => any): void\nRegister a `Transportable` class before the transport layer can marshall/unmarshall its instances.\nUser can also use class decorator [`@cid`](#cid-decorator) for class registration.\n\nExample:\n```ts\nclass A extends transport.AutoTransportable {\n field1: string,\n method1(): string {\n return this.field1;\n }\n}\n\n// Explicitly register class A in transport.\ntransport.register(A);\n```\n### marshall(jsValue: any, context: TransportContext): string\nMarshall a [transportable](#transportable-types) JavaScript value into a JSON payload with a [`TransportContext`](#transport-context).An Error will be thrown if the value is not transportable. \n\nExample:\n```js\nvar context = transport.createTransportContext();\nvar jsonPayload = transport.marshall(\n [1, 'string', napa.memory.crtAllocator], \n context);\nconsole.log(jsonPayload);\n```\n### unmarshall(json: string, context: TransportContext): any\nUnmarshall a [transportable](#transportable-types) JavaScript value from a JSON payload with a [`TransportContext`](#transport-context).An Error will be thrown if `cid` property is found and not registered with the transport layer.\n\nExample:\n```js\nvar value = transport.unmarshall(jsonPayload, context);\n```\n\n## Class `TransportContext`\nClass for [Transport Context](#transport-context), that stores shared pointers and functions during marshall/unmarshall.\n### context.saveShared(object: memory.Shareable): void\nSave a shareable object in context.\n\n### context.loadShared(handle: memory.Handle): memory.Shareable\nLoad a shareable object from handle.\n\n### context.sharedCount: number\nCount of shareable objects saved in the current context.\n\n## Interface `Transportable`\nInterface for the Transportable object.\n### transportable.cid: string\nGet accessor for [Constructor ID](#constructor-id). It is used to lookup constructor for the payload of the current class.\n\n### transportable.marshall(context: TransportContext): object\nMarshall transforms this object into a plain JavaScript object with the help of [TransportContext](#transport-context).\n\n### transportable.unmarshall(payload: object, context: TransportContext): void\nUnmarshall transforms marshalled payload into current object.\n\n## Abstract class `TransportableObject`\nTBD\n### Decorator `cid`\nTBD\n"
},
{
"path": "docs/api/zone.md",
"content": "# Namespace `zone`\n\n## Table of Contents\n- [Introduction](#intro)\n - [Multiple workers vs Multiple zones](#worker-vs-zone)\n - [Zone types](#zone-types)\n - [Zone operations](#zone-operations)\n- [API](#api)\n - [`create(id: string, settings: ZoneSettings = DEFAULT_SETTINGS): Zone`](#create)\n - [`get(id: string): Zone`](#get)\n - [`current: Zone`](#current)\n - [`node: Zone`](#node-zone)\n - Interface [`ZoneSettings`](#zone-settings)\n - [`settings.workers: number`](#zone-settings-workers)\n - Object [`DEFAULT_SETTINGS: ZoneSettings`](#default-settings)\n - Interface [`Zone`](#zone)\n - [`zone.id: string`](#zone-id)\n - [`zone.broadcast(code: string): Promise`](#broadcast-code)\n - [`zone.broadcast(function: (...args: any[]) => void, args?: any[]): Promise`](#broadcast-function)\n - [`zone.execute(moduleName: string, functionName: string, args?: any[], options?: CallOptions): Promise`](#execute-by-name)\n - [`zone.execute(function: (...args[]) => any, args?: any[], options?: CallOptions): Promise`](#execute-anonymous-function)\n - Interface [`CallOptions`](#call-options)\n - [`options.timeout: number`](#call-options-timeout)\n - Interface [`Result`](#result)\n - [`result.value: any`](#result-value)\n - [`result.payload: string`](#result-payload)\n - [`result.transportContext: transport.TransportContext`](#result-transportcontext)\n\n## Introduction\nZone is a key concept of napajs that exposes multi-thread capabilities in JavaScript world, which is a logical group of symmetric workers for specific tasks. \n\nPlease note that it's not the same `zone` concept of a context object for async calls in [Dart](https://www.dartlang.org/articles/libraries/zones), or [Angular](https://github.com/angular/zone.js), or a proposal in [TC39](https://github.com/domenic/zones).\n\n### Multiple workers vs. Multiple zones\nZone consists of one or multiple JavaScript threads, we name each thread `worker`. Workers within a zone are symmetric, which means code executed on any worker from the zone should return the same result, and the internal state of every worker should be the same from a long-running point of view. \n \nMultiple zones can co-exist in the same process, with each loading different code, bearing different states or applying different policies, like heap size, etc. The purpose of having multiple zone is to allow multiple roles for complex work, each role loads the minimum resources for its own usage.\n \n### Zone types\nThere are two types of zone:\n- **Napa zone** - zone consists of Napa.js managed JavaScript workers (V8 isolates). Can be multiple, each may contain multiple workers. Workers in Napa zone support partial Node.JS APIs.\n- **Node zone** - a 'virtual' zone which exposes Node.js eventloop, has access to full Node.js capabilities.\n\n### Zone operations \nThere are two operations, designed to reinforce the symmetry of workers within a zone:\n 1) **Broadcast** - run code that changes worker state on all workers, returning a promise for the pending operation. Through the promise, we can only know if the operation succeeded or failed. Usually we use `broadcast` to bootstrap the application, pre-cache objects, or change application settings. Function `broadcastSync` is also offered as a synchronized version of broadcast operations.\n 2) **Execute** - run code that doesn't change worker state on an arbitrary worker, returning a promise of getting the result. Execute is designed for doing the real work.\n\n Zone operations are on a basis of first-come-first-serve, while `broadcast` takes higher priority over `execute`.\n\n## API\n### create(id: string, settings: ZoneSettings): Zone\n\nIt creates a Napa zone with a string id. If a zone with the id is already created, an error will be thrown. [`ZoneSettings`](#zone-settings) can be specified for creating zones.\n\nExample 1: Create a zone with id 'zone1', using default ZoneSettings. \n```js\nvar napa = require('napajs');\nvar zone1 = napa.zone.create('zone1');\n```\nExample 2: Create a zone with id 'zone2', with 1 worker.\n```js\nvar zone2 = napa.zone.create('zone2', {\n workers: 1\n});\n```\n### get(id: string): Zone\nIt gets a reference of zone by an id. Error will be thrown if the zone doesn't exist.\n\nExample:\n```js\nvar zone = napa.zone.get('zone1');\n```\n### current: Zone\nIt returns a reference of the zone of the currently running isolate. If it's under node, it returns the [node zone](#node-zone).\n\nExample: Get current zone.\n```js\nvar zone = napa.zone.current;\n```\n### node: Zone\nIt returns a reference to the node zone. It is equivalent to `napa.zone.get('node')`;\n\nExample:\n```js\nvar zone = napa.zone.node;\n```\n## Interface `ZoneSettings`\nSettings for zones, which will be specified during the creation of zones. If not specified, [DEFAULT_SETTINGS](#default-settings) will be used.\n\n### settings.workers: number\nNumber of workers in the zone.\n\n## Object `DEFAULT_SETTINGS`\nDefault settings for creating zones.\n```js\n{\n workers: 2\n}\n```\n## Interface `Zone`\nZone is the basic concept to execute JavaScript and apply policies in Napa. You can find its definition in [Introduction](#intro). Through the Zone API, developers can broadcast JavaScript code on all workers, or execute a function on one of them. When you program against a zone, it is the best practice to ensure all workers within a zone are symmetrical to each other, that is, you should not assume a worker may maintain its own states.\n\nThe two major sets of APIs are [`broadcast`](#broadcast-code) and [`execute`](#execute-by-name), which are asynchronous operations with a few variations on their inputs.\n### zone.id: string\nIt gets the id of the zone.\n\n### zone.broadcast(code: string): Promise\\\nIt asynchronously broadcasts a snippet of JavaScript code in a string to all workers, which returns a Promise of void. If any of the workers failed to execute the code, the promise will be rejected with an error message.\n\nExample:\n\n```js\nvar napa = require('napajs');\nvar zone = napa.zone.get('zone1');\nzone.broadcast('var state = 0;')\n .then(() => {\n console.log('broadcast succeeded.');\n })\n .catch((error) => {\n console.log('broadcast failed.')\n });\n```\n\n### zone.broadcastSync(code: string): void\nIt synchronously broadcasts a snippet of JavaScript code in a string to all workers. If any of the workers failed to execute the code, an exception will be thrown with an error message.\n\nRemarks:\n\n- It's not allowed to call `broadcastSync` on current zone. It will cause a deadlock\n\nExample:\n\n```js\nvar napa = require('napajs');\nvar zone = napa.zone.get('zone1');\ntry {\n zone.broadcastSync('var state = 0;');\n console.log('broadcast succeeded.');\n} catch (error) {\n console.log('broadcast failed.')\n}\n```\n\n### zone.broadcast(function: (...args: any[]) => void | Promise\\, args?: any[]): Promise\\\nIt asynchronously broadcasts an anonymous function with its arguments to all workers, which returns a Promise of void. If any of the workers failed to execute the code, the promise will be rejected with an error message.\n\nRemarks:\n\n- If the function returns a Promise object, its state will be adopted to `broadcast`'s return value\n- The function object cannot access variables from closure\n- Unless the function object has an `origin` property, it will use the current file as `origin`, which will be used to set `__filename` and `__dirname`. (See [transporting functions](./transport.md#transporting-functions))\n- Transport context is not available in broadcast. All types that depend on [TransportContext](./transport.md#transport-context) (eg. [ShareableWrap](https://github.com/Microsoft/napajs/blob/master/inc/napa/module/shareable-wrap.h), [Transportable](./transport.md#-interface-transportable)) cannot be passed in arguments list.\n\nExample:\n\n```js\nzone.broadcast((state) => {\n require('some-module').setModuleState(state)\n }, [{field1: 1}])\n .then(() => {\n console.log('broadcast succeeded.');\n })\n .catch((error) => {\n console.log('broadcast failed:', error)\n });\n```\n\n### zone.broadcastSync(function: (...args: any[]) => void | Promise\\, args?: any[]): void\nIt synchronously broadcasts an anonymous function with its arguments to all workers. If any of the workers failed to execute the code, an exception will be thrown with an error message.\n\nRemarks:\n\n- It's not allowed to call `broadcastSync` on current zone. It will cause a deadlock\n- If the function returns a Promise object, its state will be adopted. Function `broadcastSync` will not return until that Promise resolved or rejected.\n- The function object cannot access variables from closure\n- Unless the function object has an `origin` property, it will use the current file as `origin`, which will be used to set `__filename` and `__dirname`. (See [transporting functions](./transport.md#transporting-functions))\n- Transport context is not available in broadcast. All types that depend on [TransportContext](./transport.md#transport-context) (eg. [ShareableWrap](https://github.com/Microsoft/napajs/blob/master/inc/napa/module/shareable-wrap.h), [Transportable](./transport.md#-interface-transportable)) cannot be passed in arguments list.\n\nExample:\n\n```js\ntry {\n zone.broadcastSync((state) => {\n require('some-module').setModuleState(state)\n }, [{field1: 1}]);\n console.log('broadcast succeeded.');\n} catch (error) {\n console.log('broadcast failed:', error)\n}\n```\n\n### zone.execute(moduleName: string, functionName: string, args?: any[], options?: CallOptions): Promise\\\nExecute a function asynchronously on an arbitrary worker via module name and function name. Arguments can be of any JavaScript type that is [transportable](transport.md#transportable-types). It returns a Promise of [`Result`](#result). If an error happens, either bad code, user exception, or timeout is reached, the promise will be rejected.\n\nExample: Execute function `bar` in module `foo`, with arguments [1, 'hello', { field1: 1 }]. 300ms timeout is applied.\n```js\nzone.execute(\n 'foo', \n 'bar', \n [1, \"hello\", {field1: 1}], \n { timeout: 300 })\n .then((result) => {\n console.log('execute succeeded:', result.value);\n })\n .catch((error) => {\n console.log('execute failed:', error);\n });\n\n```\n\n### zone.execute(function: (...args: any[]) => any, args?: any[], options?: CallOptions): Promise\\\n\nExecute a function object asynchronously on an arbitrary worker. Arguments can be of any JavaScript type that is [transportable](transport.md#transportable-types). It returns a Promise of [`Result`](#result). If an error happens, either bad code, user exception, or timeout is reached, promise will be rejected.\n\nRemarks:\n\n- If the function returns a Promise object, it will be adopted\n- The function object cannot access variables from closure\n- Unless the function object has an `origin` property, it will use the current file as `origin`, which will be used to set `__filename` and `__dirname`. (See [transporting functions](./transport.md#transporting-functions))\n\nExample:\n```js\nzone.execute((a: number, b: string, c: object) => {\n return a + b + JSON.stringify(c);\n }, [1, \"hello\", {field1: 1}])\n .then((result) => {\n console.log('execute succeeded:', result.value);\n })\n .catch((error) => {\n console.log('execute failed:', error);\n });\n\n```\nOutput:\n```\nexecute succeeded: 1hello{\"field1\":1}\n\n```\nAnother example demonstrates accessing `__filename` when executing an anonymous function:\n```js\n// File: /usr/file1.js\nzone.execute(() => { console.log(__filename);});\n```\nOutput:\n```\n/usr/file1.js\n```\n## Interface `CallOptions`\nInterface for options to call functions in `zone.execute`.\n\n### options.timeout: number\nTimeout in milliseconds. Default value 0 indicates no timeout.\n\n## Interface `Result`\nInterface to access the return value of [`execute`](#execute-by-name).\n\n### result.value: any\nJavaScript value returned from the function which is invoked from zone.execute/executeSync. Napa marshalls/unmarshalls [transportable values](transport.md#transportable-types) between different workers (V8 isolates). Unmarshalling will happen when the first `result.value` is queried.\n\nExample:\n```js\nvar value = result.value;\n```\n\n### result.payload: string\nMarshalled payload (in JSON) from the returned value. This field is for users that want to pass results through to its caller, where the unmarshalled value is not required. \n\nExample:\n```js\nvar payload = result.payload;\n```\n\n### result.transportContext: transport.TransportContext\n[TransportContext](transport.md#transport-context) that is required to unmarshall [`result.payload`](#result-payload) into [`result.value`](#result-value).\n\nExample:\n```js\nvar napa = require('napajs');\nvar zone = napa.zone.create('zone1');\nzone.execute(() => { return 0; }, [])\n .then((result) => {\n // Manually marshall.\n var transportContext = result.transportContext;\n var value = napa.transport.unmarshall(result.payload, result.transportContext);\n\n // result.value and manual unmarshall from payload are the same.\n assert.equal(value, result.value);\n });\n```\n"
},
{
"path": "docs/design/transport-js-builtins.md",
"content": "# Transport JavaScript standard built-in objects\n\n## Incentives\nThe abstraction of 'Transportable' lies in the center of Napa.js to efficiently share objects between JavaScript VMs (Napa workers). Except JavaScript primitive types, an object needs to implement 'Transportable' interface to make it transportable. It means [JavaScript standard built-in objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects) are not transportable unless wrappers or equivalent implementations for them are implemented by extending 'Transportable' interface. The development cost for these objects is not trivial, and new abstraction layer (wrappers or equivalent implementations) will create barriers for users to learn and adopt these new things. Moreover, developers also need to deal with the interaction between JavaScript standards objects and those wrappers or equivalent implementations.\n\nThe incentive of this design is to provide a solution to make JavaScript standard built-in objects transportable with requirements listed in the Goals section.\n\nAt the first stage, we will focus on an efficient solution to share data between Napa workers. Basically, it is about making *SharedArrayBuffer / TypedArray / DataView* transportable.\n\n## Goals\nMake Javascript standard built-in objects transportable with\n- An efficient way to share structured data, like *SharedArrayBuffer*, among Napa workers\n- Consistent APIs with ECMA standards\n- No new abstraction layers for the simplest usage\n- The least new concepts for advanced usage\n- A scalable solution to make all JavaScript standard built-in objects transportable, avoiding to make them transportable one by one.\n\n## Example\nThe below example shows how *SharedArrayBuffer* object is transported across multiple Napa workers. It will print the TypedArray 'ta' created from a *SharedArrayBuffer*, with all its elements set to 100 from different Napa workers. \n```js\nvar napa = require(\"napajs\");\nvar zone = napa.zone.create('zone', { workers: 4 });\n\nfunction foo(sab, i) {\n var ta = new Uint8Array(sab);\n ta[i] = 100;\n return i;\n}\n\nfunction run() {\n var promises = [];\n var sab = new SharedArrayBuffer(4);\n for (var i = 0; i < 4; i++) {\n promises[i] = zone.execute(foo, [sab, i]);\n }\n\n return Promise.all(promises).then(values => {\n var ta = new Uint8Array(sab);\n console.log(ta);\n });\n}\n\nrun();\n\n```\n\n## Solution\nHere we just give a high-level description of the solution. Its API will go to [docs/api/transport](https://github.com/Microsoft/napajs/blob/master/docs/api/transport.md).\n- V8 provides its value-serialization mechanism by ValueSerializer and ValueDeserializer, which is compatible with the HTML structured clone algorithm. It is a horizontal solution to serialize / deserialize JavaScript objects. ValueSerializer::Delegate and ValueDeserializer::Delegate are their inner class. They work as base classes from which developers can deprive to customize some special handling of external / shared resources, like memory used by a SharedArrayBuffer object.\n\n- **napa::v8_extensions::ExternalizedContents**\n - It holds the externalized contents (memory) of a SharedArrayBuffer instance once it is serialized via *napa::v8_extensions::Utils::SerializeValue()*.\n - Only 1 instance of ExternalizedContents will be generated for each SharedArrayBuffer. If a SharedArrayBuffer had been externalized, it will reuse the ExternalizedContents instance created before in *napa::v8_extensions::Utils::SerializeValue()*.\n\n- **napa::v8_extensions::SerializedData**\n - It is generated by *napa::v8_extensions::Utils::SerializeValue()*. It holds the serialized data of a JavaScript object, which is required during its deserialization.\n\n- **BuiltInObjectTransporter**\n - **napa::v8_extensions::Serializer, derived from v8::ValueSerializer::Delegate**\n - **napa::v8_extensions::Deserializer, derived from v8::ValueDeserializer::Delegate**\n - **static std::shared_ptr\\ v8_extensions::Utils::SerializeValue(Isolate\\* isolate, Local\\ value);**\n - Generate the *SerializedData* instance given an input value.\n - If any *SharedArrayBuffer* instances exist in the input value, their *ExternalizedContents* instances will be generated and attached to the *ShareArrayBuffer* instances respectively.\n - **static MaybeLocal\\ v8_extensions::Utils::DeserializeValue(Isolate\\* isolate, std::shared_ptr\\ data);**\n - Restore a JavaScript value from its SerializedData instance generated by *v8_extensions::Utils::SerializeValue()* before.\n\n- Currently, Napa relies on Transportable API and a registered constructor to make an object transportable. In [marshallTransform](https://github.com/Microsoft/napajs/blob/master/lib/transport/transport.ts), when a JavaScript object is detected to have a registered constructor, it will go with Napa way to marshall this object with the help of a **TransportContext** object, otherwise a non-transportable error is thrown.\n\n- Instead of throwing an error when no registered constructor is detected, the **BuiltInObjectTransporter** can help handle this object. We can use a whitelist of object types to restrict this solution to those verified types at first.\n```js\nexport function marshallTransform(jsValue: any, context: transportable.TransportContext): any {\n if (jsValue != null && typeof jsValue === 'object' && !Array.isArray(jsValue)) {\n let constructorName = Object.getPrototypeOf(jsValue).constructor.name;\n if (constructorName !== 'Object') {\n if (typeof jsValue['cid'] === 'function') {\n return (jsValue).marshall(context);\n } else if (_builtInTypeWhitelist.has(constructorName)) {\n let serializedData = builtinObjectTransporter.serializeValue(jsValue);\n if (serializedData) {\n return { _serialized : serializedData };\n } else {\n throw new Error(`Failed to serialize object with type of \\\"${constructorName}\\\".`);\n }\n } else {\n throw new Error(`Object type \\\"${constructorName}\\\" is not transportable.`);\n }\n }\n }\n return jsValue;\n}\n```\n- The reverse process will be invoked in [unmarshallTransform](https://github.com/Microsoft/napajs/edit/master/lib/transport/transport.ts) if the payload is detected to have '_serialized' property.\n```js\nfunction unmarshallTransform(payload: any, context: transportable.TransportContext): any {\n if (payload != null && payload._cid !== undefined) {\n let cid = payload._cid;\n if (cid === 'function') {\n return functionTransporter.load(payload.hash);\n }\n let subClass = _registry.get(cid);\n if (subClass == null) {\n throw new Error(`Unrecognized Constructor ID (cid) \"${cid}\". Please ensure @cid is applied on the class or transport.register is called on the class.`);\n }\n let object = new subClass();\n object.unmarshall(payload, context);\n return object;\n } else if (payload.hasOwnProperty('_serialized')) {\n return builtinObjectTransporter.deserializeValue(payload['_serialized']);\n }\n return payload;\n}\n```\n\n#### Lifecycle of SharedArrayBuffer (SAB)\n- When a SAB participates transportation among Napa workers, its life cycle will be extended till the last reference this SAB. The reference of a SAB could be:\n - SAB object in its original isolate.\n - Received SAB transported from another Napa workers, including node zone of Napa.\n - TypedArray or DataView created from the original SAB or a received SAB.\n\n- The life cycle extension during transportation is achieved through the *ExternalizedContents* *SharedPtrWrap* of the SAB.\n - When a SAB is transported for the first time, it will be externalized and its ExternalizedContents will be stored in its *SerializedData*. At the same time, the *SharedPtrWrap* of the *ExternalizedContents* will be set to the '_externalized' property of the original SAB.\n\n - When a SAB is transported for the second time or later, it will skip externalization and find its *ExternalizedContents* from its '_externalized' property, and store it to its *SerializedData*.\n\n - When a Napa worker tries to restore a transported SAB, it will find the pre-stored *ExternalizedContents*, and create a *SharedPtrWrap* for it, then set it to the to-be-restored SAB.\n\n - The life cycle of the *SharedArrayBuffer* is extended by the *SharedPtrWrap* of its *ExternalizedContents*.\n\n\n## Constraints\nThe above solution is based on the serialization / deserialization mechanism of V8. It may have the following constraints.\n- Not all [JavaScripts standard built-in objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects) are supported by Node (as a dependency of Napa in node mode) or V8 of a given version. We only provide transporting solution for those mature object types.\n- Presently, Node does not explicitly support multiple V8 isolates. There may be inconsistencies in transporting objects between Node zones and Napa zones. Extra effort might be required to make it consistent.\n"
},
{
"path": "examples/modules/README.md",
"content": "## Napa module source tree\n\nThe source codes can be organized as the structure below.\n```\n+-- napa-module-example\n +-- inc\n | +-- example.h\n +-- lib\n | +-- example.ts\n | +-- tsconfig.json\n +-- napa\n | +-- addon.cpp\n | +-- CMakeLists.txt (cmake specific)\n | +-- example-wrap.cpp\n | +-- example-wrap.h\n +-- src\n | +-- CMakeLists.txt (cmake specific)\n | +-- example.cpp\n +-- test\n | +-- test.ts\n | +-- tsconfig.json\n +-- binding.gyp (gyp specific)\n +-- CMakeLists.txt (cmake specific)\n +-- package.json\n +-- README.md\n```\n ## How to build and test ?\n For the module examples, node-gyp or cmake-js build solution is provided for your reference.\n\nPlease make sure [node-gyp](https://github.com/nodejs/node-gyp#installation) or [cmake-js](https://github.com/cmake-js/cmake-js#installation) has been set up correctly at your client, then you could follow the steps below to build and test the module examples.\n ```\n 1. go to the directory of a module example\n 2. run \"npm install\" to build the module\n 3. run \"npm test\" to build and run the module test, as well as its unittest if any\n ```\n"
},
{
"path": "examples/modules/async-number/.gitignore",
"content": "bin\nbuild\nnode_modules\ntypes\n\n# ignore all js files under lib\nlib/*.js\n\n# ignore all js files under test\ntest/*.js\n\npackage-lock.json\n"
},
{
"path": "examples/modules/async-number/.npmignore",
"content": "bin\nbuild\n\n# Exclude TypeScript source files.\nlib/*.ts\nlib/tsconfig.json\ntest/*.ts\ntest/tsconfig.json\n"
},
{
"path": "examples/modules/async-number/README.md",
"content": "# Asynchronous numbering\n\n## APIs\n\nNapa provides two functions to support asynchronous call and they work for both node.js and Napa.\n\n```cpp\nvoid napa::module::PostAsyncWork(v8::Local jsCallback,\n std::function asyncWork,\n std::function, void*)> asyncCompleteCallback);\n```\n\nIt fires asynchronous work onto separate thread.\n\n* *jsCallback*: Javascript callback given at Javascript land.\n* *asyncWork*: C++ function to run at separate thread asynchronously.\n* *asyncCompleteCallback*: C++ callback function, which has isolate instance and *jsCallback* as arguments. It's called at the same isolate with caller's one after *asyncWork* completes.\n\n```cpp\nvoid napa::module::DoAsyncWork(v8::Local jsCallback,\n const std::function)>& asyncWork,\n std::function, void*)> asyncCompleteCallback);\n```\n\nIf you have a function already supporting async, use this API.\n\n* *jsCallback*: Javascript callback given at Javascript land.\n* *asyncWork*: Function to wrap C++ function supporting async, which callback must call Napa completion callback given as argument.\n* *asyncCompleteCallback*: C++ callback function, which has isolate instance and *jsCallback* as arguments. It's called at the same isolate with caller's one after *asyncWork* completes.\n\n### Diagram\n\nThis diagram shows how asynchronous call is working corresponding to the below example,\n\n```diagram\n |-------------------------| |------------------------| |------------------------------------| |-------------------|\n(V8 thread)-----| Call *increase()* at JS |-----| Run the next statement |-------------------| Run *asyncCompleteCallback* at C++ |-----| Call *jsCallback* |\n |-------------------------| |------------------------| |------------------------------------| |-------------------|\n | +\n | |\n |----------| |\n | |\n + |\n |------------------| |--------------------------------------------| |\n (thread)-----| Run *asyncWork* |-----| Post a task to run *asyncCompleteCallback* |---------|\n |------------------| |--------------------------------------------|\n```\n\n## C++ module\n\nThis example shows how to create async module. It keeps one number and three APIs operating on it as follows,\n\n* *Increase*: It increases a number by a given parameter in separate thread and post a completion to run Javascript callback at the next execution loop.\n* *IncreaseSync*: It increases a number by a given parameter in the same thread and post a completion to run Javascript callback at the next execution loop.\n* *Now*: It returns the current value of a number.\n\n```cpp\n#include \n\n#include \n#include \n\nnamespace napa {\nnamespace demo {\n\nusing namespace v8;\n\nnamespace {\n std::atomic _now(0);\n}\n\n/// It increases a number by a given parameter asynchronously and runs a callback at the next execution loop. \nvoid Increase(const FunctionCallbackInfo& args) {\n auto isolate = args.GetIsolate();\n\n CHECK_ARG(isolate,\n args.Length() == 2 && args[0]->IsUint32() && args[1]->IsFunction(),\n \"It requires unsigned integer and callback as arguments\");\n\n auto value = args[0]->Uint32Value();\n\n napa::module::PostAsyncWork(Local::Cast(args[1]),\n [value]() {\n // This runs in a separate thread.\n _now += value;\n return reinterpret_cast(static_cast(_now.load()));\n },\n [](auto jsCallback, void* result) {\n // This runs in the same thread as the one Increase() is called in.\n auto isolate = Isolate::GetCurrent();\n\n int32_t argc = 1;\n Local argv[] =\n { Integer::NewFromUnsigned(isolate, static_cast(reinterpret_cast(result))) };\n\n jsCallback->Call(isolate->GetCurrentContext()->Global(), argc, argv);\n }\n );\n}\n\n/// It increases a number by a given parameter synchronously and runs a callback at the next execution loop. \nvoid IncreaseSync(const FunctionCallbackInfo& args) {\n auto isolate = args.GetIsolate();\n\n CHECK_ARG(isolate,\n args.Length() == 2 && args[0]->IsUint32() && args[1]->IsFunction(),\n \"It requires unsigned integer and callback as arguments\");\n\n auto value = args[0]->Uint32Value();\n\n napa::module::DoAsyncWork(Local::Cast(args[1]),\n [value](auto complete) {\n // This runs in the same thread.\n _now += value;\n complete(reinterpret_cast(static_cast(_now.load())));\n },\n [](auto jsCallback, void* result) {\n // This runs in the same thread as the one IncreaseSync() is called in.\n auto isolate = Isolate::GetCurrent();\n\n int32_t argc = 1;\n Local argv[] =\n { Integer::NewFromUnsigned(isolate, static_cast(reinterpret_cast(result))) };\n\n jsCallback->Call(isolate->GetCurrentContext()->Global(), argc, argv);\n }\n );\n}\n\n/// It returns the current value of a number. \nvoid Now(const FunctionCallbackInfo& args) {\n auto isolate = args.GetIsolate();\n HandleScope scope(isolate);\n\n args.GetReturnValue().Set(Integer::NewFromUnsigned(isolate, _now));\n}\n\nvoid Init(Local