{"action":"created","comment":{"url":"https://api.github.com/repos/nodejs/node-eps/pulls/comments/61758146","id":61758146,"diff_hunk":"@@ -0,0 +1,179 @@\n+| Title  | ABI Stable Module API                 |\n+|--------|---------------------------------------|\n+| Author | @mhdawson, @stefanbu, @Ianwjhalliday  |\n+| Status | DRAFT                                 |\n+| Date   | 2016-04-29                            |\n+\n+# Introduction\n+\n+The module ecosystem is one of the features making Node.js the fastest\n+growing runtime.  An important subset of modules are those which have a\n+native component. In specific cases it is important to be able to leverage native\n+code in order to be able to:\n+\n+* use existing third party components written in C/C++\n+* access physical devices, for example a serial port\n+* expose functionality from the operating system not otherwise available\n+* achieve higher speed than possible in native JavaScript\n+\n+There is an existing interface (addons) that allows you to build these modules\n+as a dynamically-linked shared module that can be loaded into Node.js and\n+used as an ordinary Node.js module (for more details see\n+https://nodejs.org/api/addons.html)\n+\n+Unfortunately in the existing implementation the V8\n+(the JavaScript runtime for Node.js) APIs are exposed to modules. In \n+addition Google changes these APIs on a regular basis. This results in \n+the following issues:\n+\n+* Native modules must be recompiled for each version of Node.js\n+* The code within modules must often be modified for a new version of\n+  Node.js\n+* It.s not clear which parts of the V8 API the Node.js community believes\n+  are safe/unsafe to use in terms of long term support for that use.\n+* Modules written against the V8 APIs may or may not be able to work\n+  with alternate JavaScript engines when/if Node.js supports them.\n+\n+The Nan project (https://github.com/nodejs/nan) can be used to limit\n+the cases when modules must be updated in order to work with new versions\n+of Node.js but does not address the other issues as it does not\n+encapsulate the V8 argument types such that modules still need\n+to be recompiled for new Node.js versions.\n+\n+# Proposed Action\n+\n+The goal of this eps is to define an API that:\n+\n+* Provides a stable API which is not tied to the current\n+  or further APIs provided by V8\n+* Allows native modules built as shared libraries to be used\n+  with different versions of Node.js\n+* Makes it clear which APIs can use with the expectation\n+  of not being affected by changes in the JavaScript engine\n+  or Node.js release\n+\n+# Background\n+\n+There have been ongoing discussions on a new module API in both the\n+community api working group (https://github.com/nodejs/api), other\n+issues in the Node.js  issue tracker, and the recent community Node.js\n+face-to-face VM summit (https://github.com/jasnell/vm-summit).\n+\n+In that summit there was agreement that we wanted to define this\n+module API.  The general approach was to be:\n+\n+* Start with Nan, trim down to minimal subset based on module usage \n+  and inspection.\n+* Add in VM agnostic methods for object lifecycle management.\n+* Add in VM agnostic exception management\n+* Define C/C++ types for the API which are independent from V8\n+  (Nan currently uses the V8 types).\n+* Use the Nan examples to work through the API and build up the\n+  definition of the key methods.\n+* Validate on most used modules in the ecosystem\n+* Complete performance analysis to confirm accepted level of overhead.\n+\n+Notes/details on other related work and the current experimental progress\n+on implementing this eps can be found in:\n+https://docs.google.com/document/d/1bX9SZKufbfhr7ncXL9fFev2LrljymtFZdWpwmv7mB9g/edit#heading=h.ln9aj9qjo969\n+\n+# API definition\n+\n+**WORK IN PROGRESS, NOT ANYWHERE NEAR COMPLETE.** \n+\n+This API will be built up from a minimal set as we explore the full set of Nan functions.  To start it will only include the minimal set that we need to get started.  What this means is we have not define the full API yet but instead want to give a feel of the general shape (which is not really quite there yet). \n+\n+One of the main gaps is that we have not filled in the table for node::ni::New(ni_env,...) yet so we can not fully specify the arguments for the rest of the calls.  This will be one of the priorities as we work through the first Nan example.\n+\n+The proposal introduces the node::ni namespace to encapsulate all native module interface functions. ni_env is an opaque handle to a given instance of a node environment for use by a native module.  In the case of a C version of the interface ni_env would be the first paramter to all methods.  In the case of a C++ version all methods would be functions callable on an ni_env object.\n+\n+The definition of the API will be broken down into the following categories:\n+\n+## core functions\n+\n+### C setting javascript values\n+<PRE>\n+node::ni::SetMethod(ni_env, recv, name, callback)\n+node::ni::SetPrototypeMethod(ni_env, recv, name, callback)\n+node::ni::SetTemplate(ni_env,...)\n+node::ni::SetPrototypeTemplate(ni_env,...)\n+node::ni::SetInstanceTemplate(ni_env,...)","path":"00X-ABI-Stable-Module-API.md","position":100,"original_position":100,"commit_id":"ac07e65121a7dce5055b9b6fb04917fd8eb3d9a7","original_commit_id":"ac07e65121a7dce5055b9b6fb04917fd8eb3d9a7","user":{"login":"kkoopa","id":4103081,"avatar_url":"https://avatars.githubusercontent.com/u/4103081?v=3","gravatar_id":"","url":"https://api.github.com/users/kkoopa","html_url":"https://github.com/kkoopa","followers_url":"https://api.github.com/users/kkoopa/followers","following_url":"https://api.github.com/users/kkoopa/following{/other_user}","gists_url":"https://api.github.com/users/kkoopa/gists{/gist_id}","starred_url":"https://api.github.com/users/kkoopa/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kkoopa/subscriptions","organizations_url":"https://api.github.com/users/kkoopa/orgs","repos_url":"https://api.github.com/users/kkoopa/repos","events_url":"https://api.github.com/users/kkoopa/events{/privacy}","received_events_url":"https://api.github.com/users/kkoopa/received_events","type":"User","site_admin":false},"body":"Now I am even more confused. We were discussing V8's [templates](developers.google.com/v8/embed#templates) which are used to build functions and other objects. They are not a matter of ease-of-use, but a necessity for building functions and other objects with V8. Somehow I get the impression that you are thinking of C++ templates, which are an entirely different matter, having no connection to V8's templates.","created_at":"2016-05-02T15:53:56Z","updated_at":"2016-05-02T15:53:56Z","html_url":"https://github.com/nodejs/node-eps/pull/20#discussion_r61758146","pull_request_url":"https://api.github.com/repos/nodejs/node-eps/pulls/20","_links":{"self":{"href":"https://api.github.com/repos/nodejs/node-eps/pulls/comments/61758146"},"html":{"href":"https://github.com/nodejs/node-eps/pull/20#discussion_r61758146"},"pull_request":{"href":"https://api.github.com/repos/nodejs/node-eps/pulls/20"}}},"pull_request":{"url":"https://api.github.com/repos/nodejs/node-eps/pulls/20","id":68437319,"html_url":"https://github.com/nodejs/node-eps/pull/20","diff_url":"https://github.com/nodejs/node-eps/pull/20.diff","patch_url":"https://github.com/nodejs/node-eps/pull/20.patch","issue_url":"https://api.github.com/repos/nodejs/node-eps/issues/20","number":20,"state":"open","locked":false,"title":"Initial version of eps for ABI-Stable-Module-API","user":{"login":"mhdawson","id":9373002,"avatar_url":"https://avatars.githubusercontent.com/u/9373002?v=3","gravatar_id":"","url":"https://api.github.com/users/mhdawson","html_url":"https://github.com/mhdawson","followers_url":"https://api.github.com/users/mhdawson/followers","following_url":"https://api.github.com/users/mhdawson/following{/other_user}","gists_url":"https://api.github.com/users/mhdawson/gists{/gist_id}","starred_url":"https://api.github.com/users/mhdawson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mhdawson/subscriptions","organizations_url":"https://api.github.com/users/mhdawson/orgs","repos_url":"https://api.github.com/users/mhdawson/repos","events_url":"https://api.github.com/users/mhdawson/events{/privacy}","received_events_url":"https://api.github.com/users/mhdawson/received_events","type":"User","site_admin":false},"body":"First cut of the ABI-Stable-Module-API eps.  It is far\r\nfrom complete but is intended to allow insight into the\r\ncurrent direction/status and will be updated regularly\r\nas we progress along the investigation and can make\r\nthe API definition more complete.","created_at":"2016-04-29T21:34:31Z","updated_at":"2016-05-02T15:53:56Z","closed_at":null,"merged_at":null,"merge_commit_sha":"1cf12bf25c4a19d25a9bfc8d67fe751a1583d753","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/nodejs/node-eps/pulls/20/commits","review_comments_url":"https://api.github.com/repos/nodejs/node-eps/pulls/20/comments","review_comment_url":"https://api.github.com/repos/nodejs/node-eps/pulls/comments{/number}","comments_url":"https://api.github.com/repos/nodejs/node-eps/issues/20/comments","statuses_url":"https://api.github.com/repos/nodejs/node-eps/statuses/ac07e65121a7dce5055b9b6fb04917fd8eb3d9a7","head":{"label":"mhdawson:master","ref":"master","sha":"ac07e65121a7dce5055b9b6fb04917fd8eb3d9a7","user":{"login":"mhdawson","id":9373002,"avatar_url":"https://avatars.githubusercontent.com/u/9373002?v=3","gravatar_id":"","url":"https://api.github.com/users/mhdawson","html_url":"https://github.com/mhdawson","followers_url":"https://api.github.com/users/mhdawson/followers","following_url":"https://api.github.com/users/mhdawson/following{/other_user}","gists_url":"https://api.github.com/users/mhdawson/gists{/gist_id}","starred_url":"https://api.github.com/users/mhdawson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mhdawson/subscriptions","organizations_url":"https://api.github.com/users/mhdawson/orgs","repos_url":"https://api.github.com/users/mhdawson/repos","events_url":"https://api.github.com/users/mhdawson/events{/privacy}","received_events_url":"https://api.github.com/users/mhdawson/received_events","type":"User","site_admin":false},"repo":{"id":57413801,"name":"node-eps","full_name":"mhdawson/node-eps","owner":{"login":"mhdawson","id":9373002,"avatar_url":"https://avatars.githubusercontent.com/u/9373002?v=3","gravatar_id":"","url":"https://api.github.com/users/mhdawson","html_url":"https://github.com/mhdawson","followers_url":"https://api.github.com/users/mhdawson/followers","following_url":"https://api.github.com/users/mhdawson/following{/other_user}","gists_url":"https://api.github.com/users/mhdawson/gists{/gist_id}","starred_url":"https://api.github.com/users/mhdawson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mhdawson/subscriptions","organizations_url":"https://api.github.com/users/mhdawson/orgs","repos_url":"https://api.github.com/users/mhdawson/repos","events_url":"https://api.github.com/users/mhdawson/events{/privacy}","received_events_url":"https://api.github.com/users/mhdawson/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/mhdawson/node-eps","description":"Node.js Enhancement Proposals for discussion on future API additions/changes to Node core","fork":true,"url":"https://api.github.com/repos/mhdawson/node-eps","forks_url":"https://api.github.com/repos/mhdawson/node-eps/forks","keys_url":"https://api.github.com/repos/mhdawson/node-eps/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mhdawson/node-eps/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mhdawson/node-eps/teams","hooks_url":"https://api.github.com/repos/mhdawson/node-eps/hooks","issue_events_url":"https://api.github.com/repos/mhdawson/node-eps/issues/events{/number}","events_url":"https://api.github.com/repos/mhdawson/node-eps/events","assignees_url":"https://api.github.com/repos/mhdawson/node-eps/assignees{/user}","branches_url":"https://api.github.com/repos/mhdawson/node-eps/branches{/branch}","tags_url":"https://api.github.com/repos/mhdawson/node-eps/tags","blobs_url":"https://api.github.com/repos/mhdawson/node-eps/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mhdawson/node-eps/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mhdawson/node-eps/git/refs{/sha}","trees_url":"https://api.github.com/repos/mhdawson/node-eps/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mhdawson/node-eps/statuses/{sha}","languages_url":"https://api.github.com/repos/mhdawson/node-eps/languages","stargazers_url":"https://api.github.com/repos/mhdawson/node-eps/stargazers","contributors_url":"https://api.github.com/repos/mhdawson/node-eps/contributors","subscribers_url":"https://api.github.com/repos/mhdawson/node-eps/subscribers","subscription_url":"https://api.github.com/repos/mhdawson/node-eps/subscription","commits_url":"https://api.github.com/repos/mhdawson/node-eps/commits{/sha}","git_commits_url":"https://api.github.com/repos/mhdawson/node-eps/git/commits{/sha}","comments_url":"https://api.github.com/repos/mhdawson/node-eps/comments{/number}","issue_comment_url":"https://api.github.com/repos/mhdawson/node-eps/issues/comments{/number}","contents_url":"https://api.github.com/repos/mhdawson/node-eps/contents/{+path}","compare_url":"https://api.github.com/repos/mhdawson/node-eps/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mhdawson/node-eps/merges","archive_url":"https://api.github.com/repos/mhdawson/node-eps/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mhdawson/node-eps/downloads","issues_url":"https://api.github.com/repos/mhdawson/node-eps/issues{/number}","pulls_url":"https://api.github.com/repos/mhdawson/node-eps/pulls{/number}","milestones_url":"https://api.github.com/repos/mhdawson/node-eps/milestones{/number}","notifications_url":"https://api.github.com/repos/mhdawson/node-eps/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mhdawson/node-eps/labels{/name}","releases_url":"https://api.github.com/repos/mhdawson/node-eps/releases{/id}","deployments_url":"https://api.github.com/repos/mhdawson/node-eps/deployments","created_at":"2016-04-29T21:27:22Z","updated_at":"2016-04-29T04:48:17Z","pushed_at":"2016-04-29T21:32:19Z","git_url":"git://github.com/mhdawson/node-eps.git","ssh_url":"git@github.com:mhdawson/node-eps.git","clone_url":"https://github.com/mhdawson/node-eps.git","svn_url":"https://github.com/mhdawson/node-eps","homepage":null,"size":34,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"nodejs:master","ref":"master","sha":"8e2ac8ffbe17c837ffa9546f9324727040d0ebce","user":{"login":"nodejs","id":9950313,"avatar_url":"https://avatars.githubusercontent.com/u/9950313?v=3","gravatar_id":"","url":"https://api.github.com/users/nodejs","html_url":"https://github.com/nodejs","followers_url":"https://api.github.com/users/nodejs/followers","following_url":"https://api.github.com/users/nodejs/following{/other_user}","gists_url":"https://api.github.com/users/nodejs/gists{/gist_id}","starred_url":"https://api.github.com/users/nodejs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nodejs/subscriptions","organizations_url":"https://api.github.com/users/nodejs/orgs","repos_url":"https://api.github.com/users/nodejs/repos","events_url":"https://api.github.com/users/nodejs/events{/privacy}","received_events_url":"https://api.github.com/users/nodejs/received_events","type":"Organization","site_admin":false},"repo":{"id":48204104,"name":"node-eps","full_name":"nodejs/node-eps","owner":{"login":"nodejs","id":9950313,"avatar_url":"https://avatars.githubusercontent.com/u/9950313?v=3","gravatar_id":"","url":"https://api.github.com/users/nodejs","html_url":"https://github.com/nodejs","followers_url":"https://api.github.com/users/nodejs/followers","following_url":"https://api.github.com/users/nodejs/following{/other_user}","gists_url":"https://api.github.com/users/nodejs/gists{/gist_id}","starred_url":"https://api.github.com/users/nodejs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nodejs/subscriptions","organizations_url":"https://api.github.com/users/nodejs/orgs","repos_url":"https://api.github.com/users/nodejs/repos","events_url":"https://api.github.com/users/nodejs/events{/privacy}","received_events_url":"https://api.github.com/users/nodejs/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/nodejs/node-eps","description":"Node.js Enhancement Proposals for discussion on future API additions/changes to Node core","fork":false,"url":"https://api.github.com/repos/nodejs/node-eps","forks_url":"https://api.github.com/repos/nodejs/node-eps/forks","keys_url":"https://api.github.com/repos/nodejs/node-eps/keys{/key_id}","collaborators_url":"https://api.github.com/repos/nodejs/node-eps/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/nodejs/node-eps/teams","hooks_url":"https://api.github.com/repos/nodejs/node-eps/hooks","issue_events_url":"https://api.github.com/repos/nodejs/node-eps/issues/events{/number}","events_url":"https://api.github.com/repos/nodejs/node-eps/events","assignees_url":"https://api.github.com/repos/nodejs/node-eps/assignees{/user}","branches_url":"https://api.github.com/repos/nodejs/node-eps/branches{/branch}","tags_url":"https://api.github.com/repos/nodejs/node-eps/tags","blobs_url":"https://api.github.com/repos/nodejs/node-eps/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/nodejs/node-eps/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/nodejs/node-eps/git/refs{/sha}","trees_url":"https://api.github.com/repos/nodejs/node-eps/git/trees{/sha}","statuses_url":"https://api.github.com/repos/nodejs/node-eps/statuses/{sha}","languages_url":"https://api.github.com/repos/nodejs/node-eps/languages","stargazers_url":"https://api.github.com/repos/nodejs/node-eps/stargazers","contributors_url":"https://api.github.com/repos/nodejs/node-eps/contributors","subscribers_url":"https://api.github.com/repos/nodejs/node-eps/subscribers","subscription_url":"https://api.github.com/repos/nodejs/node-eps/subscription","commits_url":"https://api.github.com/repos/nodejs/node-eps/commits{/sha}","git_commits_url":"https://api.github.com/repos/nodejs/node-eps/git/commits{/sha}","comments_url":"https://api.github.com/repos/nodejs/node-eps/comments{/number}","issue_comment_url":"https://api.github.com/repos/nodejs/node-eps/issues/comments{/number}","contents_url":"https://api.github.com/repos/nodejs/node-eps/contents/{+path}","compare_url":"https://api.github.com/repos/nodejs/node-eps/compare/{base}...{head}","merges_url":"https://api.github.com/repos/nodejs/node-eps/merges","archive_url":"https://api.github.com/repos/nodejs/node-eps/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/nodejs/node-eps/downloads","issues_url":"https://api.github.com/repos/nodejs/node-eps/issues{/number}","pulls_url":"https://api.github.com/repos/nodejs/node-eps/pulls{/number}","milestones_url":"https://api.github.com/repos/nodejs/node-eps/milestones{/number}","notifications_url":"https://api.github.com/repos/nodejs/node-eps/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/nodejs/node-eps/labels{/name}","releases_url":"https://api.github.com/repos/nodejs/node-eps/releases{/id}","deployments_url":"https://api.github.com/repos/nodejs/node-eps/deployments","created_at":"2015-12-17T23:39:07Z","updated_at":"2016-05-02T13:39:20Z","pushed_at":"2016-04-29T21:34:31Z","git_url":"git://github.com/nodejs/node-eps.git","ssh_url":"git@github.com:nodejs/node-eps.git","clone_url":"https://github.com/nodejs/node-eps.git","svn_url":"https://github.com/nodejs/node-eps","homepage":null,"size":71,"stargazers_count":80,"watchers_count":80,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":12,"mirror_url":null,"open_issues_count":12,"forks":12,"open_issues":12,"watchers":80,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/nodejs/node-eps/pulls/20"},"html":{"href":"https://github.com/nodejs/node-eps/pull/20"},"issue":{"href":"https://api.github.com/repos/nodejs/node-eps/issues/20"},"comments":{"href":"https://api.github.com/repos/nodejs/node-eps/issues/20/comments"},"review_comments":{"href":"https://api.github.com/repos/nodejs/node-eps/pulls/20/comments"},"review_comment":{"href":"https://api.github.com/repos/nodejs/node-eps/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/nodejs/node-eps/pulls/20/commits"},"statuses":{"href":"https://api.github.com/repos/nodejs/node-eps/statuses/ac07e65121a7dce5055b9b6fb04917fd8eb3d9a7"}}}}