node-cpp updates #43

mapsam · 2017-11-14T20:41:06Z

What changed?

adding new "concurrency" example section
porting https://github.com/mapbox/versioning-node-cpp into this doc to resolve Move node-cpp-versioning into this repo #11
remove "naming conventions" since it's a little too opinionated and we don't even follow it
add a table of contents to this doc
update "developing addons" section to essentially point at node-cpp-skel for docs
add this doc to the glossary under "node addon"
add profiling to glossary
add concurrency to glossary with link to new doc section

Best viewed https://github.com/mapbox/cpp/blob/concurrency-additions/node-cpp.md

cc @GretaCB @mapbox/core-tech

GretaCB

I'm going to follow this up with a branch that implements all of my comments as part of this review

GretaCB · 2017-11-14T21:10:47Z

node-cpp.md

@@ -1,66 +1,115 @@
 # Node.js C++ Addons

-The following document outlines Mapbox's approach to writing C++ modules for Node.js (often referred to as _addons_).
+* [Why create a node addon?](#why-create-a-node-addon)


heck yes, TOC

GretaCB · 2017-11-14T21:11:29Z

node-cpp.md

+* [Versioning](#versioning)
+* [Additional Resources](#additional-resources)
+
+The following document outlines Mapbox's general approach to writing C++ modules for Node.js (often referred to as _addons_), and they _why_. Check out [node-cpp-skel](https://github.com/mapbox/node-cpp-skel), a skeleton library for creating a Node.js addon, to learn more about _how_ to create an addon.


and the why

GretaCB · 2017-11-14T21:15:00Z

node-cpp.md


-To swing between Node and C++, the Node community maintains a project called [_NAN_](https://github.com/nodejs/nan) (Native Abstractions for Node.js) that simplifies running different versions of Node and, subsequently, v8. NAN is a header-only C++ library that provides a set of Macros for developing Node.js addons. Check out the [usage](https://github.com/nodejs/nan#usage) guidelines.
+1. To port a C++ project to Node to expose a new interface for the tool (like Mapnik & Node Mapnik)


Perhaps link to Node glossary term

GretaCB · 2017-11-14T21:16:01Z

node-cpp.md

-More examples of how to port C++ libraries to node can be found at [nodejs.org/api/addons](http://nodejs.org/api/addons.html). See https://nodesource.com/blog/c-add-ons-for-nodejs-v4/ for a detailed summary of the origins of Nan. And see http://blog.reverberate.org/2016/10/17/native-extensions-memory-management-part2-javascript-v8.html for a good introduction to v8 that is not specific to node.js.
+**Concurrency**
+
+Concurrency is the process of executing different pieces of the same process to allow for parallel execution of these pieces [[wikipedia](https://en.wikipedia.org/wiki/Concurrency_(computer_science))]. Node.js addons allow us to take advantage of concurrent operations within our node applications by reaching into more than just the v8 thread, but this can result in a few surprises. In the example below, we’ve passed data from our node application, into the v8 thread, and subsequently into our worker threadpool. Here there are multiple workers executing code at the same time. In our worker, we have the following line:


Link to v8 glossary term

GretaCB · 2017-11-14T21:18:28Z

node-cpp.md

+
+![concurrent](https://mapbox.s3.amazonaws.com/cpp-assets/addon-hey-concurrent.gif)
+
+We run the following script node index.js. Here’s the output:


When we run the script again from within the threadpool, here's the output:

GretaCB · 2017-11-14T21:19:56Z

node-cpp.md

+raeol
+```
+
+That’s a messy burger! 🍔 std::cout is logging at the same time and space is being filled concurrently. We’re literally seeing concurrency happen here–awesome! This makes testing pretty hard though. There are a few options to get your logs in order, such as adding a mutex to keep things straight. Since we’re just testing, we can tell our computer to only run this script with a single thread - forcing our application to run non-concurrently. We pass the following before running our script:


Link to mutex (not in our glossary yet)

GretaCB · 2017-11-14T21:21:03Z

node-cpp.md

+royal with cheese
+royal with cheese
+royal with cheese
+```

 ### How is it different than a C++ project?


How is an Node addon different than a C++ project?

👍

a an Node addon

GretaCB · 2017-11-14T21:26:16Z

node-cpp.md

-Developing an addon requires Node.js, NPM, and a C++ compiler.
-
-* makefile: home to all of the development commands for building binaries, installing dependencies, and running tests
+Developing an addon requires Node.js, NPM, and a C++ compiler. Check out node-cpp-skel's "extended tour" for an up-to-date and opinionated approach to developing an addon. Additinally, the repository has docs on [running benchmarks](https://github.com/mapbox/node-cpp-skel/blob/master/docs/benchmarking.md), [publishing binaries](https://github.com/mapbox/node-cpp-skel/blob/master/docs/publishing-binaries.md), and a breakdown of all the [necessary components](https://github.com/mapbox/node-cpp-skel/blob/master/docs/extended-tour.md#configuration-files) to make it run.


Add link to node-cpp-skel's "extended tour"

mapsam · 2017-11-14T21:48:33Z

@GretaCB 👍 for all these edits. Thank you!

GretaCB · 2017-11-14T22:14:43Z

@mapsam Just pushed some more changes

GretaCB · 2017-11-14T22:24:35Z

remove "naming conventions" since it's a little too opinionated and we don't even follow it

Agreed that from an open source perspective, this is opinionated. Perhaps we can add a blurb of what we've found useful and mostly implemented to help differentiate between node and C++ projects, for example

vt-shaver
vt-shaver-cpp
geojson-cpp
geojson.hpp o_O

mapsam · 2017-11-14T22:38:19Z

@GretaCB how about we add it back once we can review the rest of our repos? That section was added purely from my own perspective, but I imagine so many more of our repositories follow other conventions as well, i.e. starting with mapbox- first 🤷‍♂️

mapsam · 2017-11-14T22:38:38Z

Thanks for the changes @GretaCB! 🙏

GretaCB · 2017-11-16T22:31:08Z

@mapsam just tied in a bunch of other pieces and added more glossary terms. If looks 👍 , I can merge

mapsam · 2017-11-16T23:25:36Z

@GretaCB thanks so much! Merge away

springmeyer · 2017-11-21T20:08:35Z

Great work on this @mapsam @GretaCB.

mapsam added 3 commits November 14, 2017 12:33

update node-cpp with concurrency and versioning examples

a9fea9f

add image urls

424ffa1

toc, remove naming conventions

a6f608e

mapsam requested a review from GretaCB November 14, 2017 20:41

GretaCB reviewed Nov 14, 2017

View reviewed changes

add more links, minor edits

703cf61

other minor edits

14f5250

gretacb added 5 commits November 16, 2017 15:49

add node addon to glossary

fd18e6f

update toc

b88f0cc

add profiling as term in glossary

745740d

add concurrency to glossary and link to new doc section

979a31e

point to glossary term instead

0d50bc4

GretaCB merged commit 3a9b478 into master Nov 16, 2017

GretaCB deleted the concurrency-additions branch November 16, 2017 23:40

springmeyer mentioned this pull request Nov 27, 2017

Add profiling/performance docs mapbox/node-cpp-skel#30

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

node-cpp updates #43

node-cpp updates #43

mapsam commented Nov 14, 2017 •

edited by GretaCB

Loading

GretaCB left a comment

GretaCB Nov 14, 2017

GretaCB Nov 14, 2017

GretaCB Nov 14, 2017

GretaCB Nov 14, 2017

GretaCB Nov 14, 2017

GretaCB Nov 14, 2017

GretaCB Nov 14, 2017

mapsam Nov 14, 2017

GretaCB Nov 14, 2017

mapsam commented Nov 14, 2017

GretaCB commented Nov 14, 2017

GretaCB commented Nov 14, 2017 •

edited

Loading

mapsam commented Nov 14, 2017

mapsam commented Nov 14, 2017

GretaCB commented Nov 16, 2017

mapsam commented Nov 16, 2017

springmeyer commented Nov 21, 2017


		To swing between Node and C++, the Node community maintains a project called [_NAN_](https://github.com/nodejs/nan) (Native Abstractions for Node.js) that simplifies running different versions of Node and, subsequently, v8. NAN is a header-only C++ library that provides a set of Macros for developing Node.js addons. Check out the [usage](https://github.com/nodejs/nan#usage) guidelines.
		1. To port a C++ project to Node to expose a new interface for the tool (like Mapnik & Node Mapnik)


		![concurrent](https://mapbox.s3.amazonaws.com/cpp-assets/addon-hey-concurrent.gif)

		We run the following script node index.js. Here’s the output:

node-cpp updates #43

node-cpp updates #43

Conversation

mapsam commented Nov 14, 2017 • edited by GretaCB Loading

What changed?

GretaCB left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mapsam commented Nov 14, 2017

GretaCB commented Nov 14, 2017

GretaCB commented Nov 14, 2017 • edited Loading

mapsam commented Nov 14, 2017

mapsam commented Nov 14, 2017

GretaCB commented Nov 16, 2017

mapsam commented Nov 16, 2017

springmeyer commented Nov 21, 2017

mapsam commented Nov 14, 2017 •

edited by GretaCB

Loading

GretaCB commented Nov 14, 2017 •

edited

Loading