From 08c277cad079dc985e8ac997787b4e0343215b8d Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Thu, 18 Oct 2018 18:12:59 -0700
Subject: [PATCH] doc: document that addMembership must be called once in a
 cluster

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

diff --git a/doc/api/dgram.md b/doc/api/dgram.md
index 069ec40b4eff37..4be2c6089d8a69 100644
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@@ -95,6 +95,24 @@ 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.
 
+When sharing a UDP socket across multiple `cluster` workers, the
+`socket.addMembership()` function must only be called *only once* or an
+`EADDRINUSE` error will occur:
+
+```js
+const cluster = require('cluster');
+const dgram = require('dgram');
+ if (cluster.isMaster) {
+   cluster.fork(); // Works ok
+   cluster.fork(); // Fails with EADDRINUSE
+} else {
+  const s = dgram.createSocket('udp4');
+  s.bind(1234, () => {
+    s.addMembership('224.0.0.114');
+  });
+}
+```
+
 ### socket.address()
 <!-- YAML
 added: v0.1.99