From 5292a500eb60c90aeddc43b31d821f8ac968ac56 Mon Sep 17 00:00:00 2001
From: Daijiro Wachi <daijiro.wachi@gmail.com>
Date: Sun, 22 Oct 2017 11:36:38 +0200
Subject: [PATCH] doc: Add notes how addMembership should be managed

Fixes: https://github.com/nodejs/node/issues/12572
---
 doc/api/dgram.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/api/dgram.md b/doc/api/dgram.md
index 980537640f6e8d..7dfb68816ade47 100644
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@@ -95,6 +95,26 @@ Tells the kernel to join a multicast group at the given `multicastAddress` and
 one interface and will add membership to it. To add membership to every
 available interface, call `addMembership` multiple times, once per interface.
 
+UDP works as a bit special with cluster. When `dgram` creates a socket in the
+master process, each worker gets a copy as in `dup(2)``, except the actual
+mechanism is `sendmsg(2)`` with a SCM_RIGHTS vector. Therefor, `.addMembership`
+needs to be managed to be called only once.
+
+```js
+const cluster = require('cluster');
+const dgram = require('dgram');
+
+if (cluster.isMaster) {
+   cluster.fork(); // ok
+   cluster.fork(); // EADDRINUSE
+} else {
+  const s = dgram.createSocket('udp4');
+  s.bind(1234, () => {
+    s.addMembership('224.0.0.114');
+  });
+}
+```
+
 ### socket.address()
 <!-- YAML
 added: v0.1.99