add docs for socket/server/timer unref and ref

nodejs · Jul 23, 2012 · bdd1a74 · bdd1a74
1 parent cd6122e
commit bdd1a74
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 0 deletions.
diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown
@@ -207,3 +207,15 @@ this.
 
 If `multicastInterface` is not specified, the OS will try to drop membership to all valid
 interfaces.
+
+### dgram.unref()
+
+Calling `unref` on a socket will allow the program to exit if this is the only
+active socket in the event system. If the socket is already `unref`d calling
+`unref` again will have no effect.
+
+### dgram.ref()
+
+Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not*
+let the program exit if it's the only socket left (the default behavior). If
+the socket is `ref`d calling `ref` again will have no effect.
diff --git a/doc/api/net.markdown b/doc/api/net.markdown
@@ -207,6 +207,18 @@ Example:
 
 Don't call `server.address()` until the `'listening'` event has been emitted.
 
+### server.unref()
+
+Calling `unref` on a server will allow the program to exit if this is the only
+active server in the event system. If the server is already `unref`d calling
+`unref` again will have no effect.
+
+### server.ref()
+
+Opposite of `unref`, calling `ref` on a previously `unref`d server will *not*
+let the program exit if it's the only server left (the default behavior). If
+the server is `ref`d calling `ref` again will have no effect.
+
 ### server.maxConnections
 
 Set this property to reject connections when the server's connection count gets
@@ -385,6 +397,18 @@ socket as reported by the operating system. Returns an object with
 three properties, e.g.
 `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`
 
+### socket.unref()
+
+Calling `unref` on a socket will allow the program to exit if this is the only
+active socket in the event system. If the socket is already `unref`d calling
+`unref` again will have no effect.
+
+### socket.ref()
+
+Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not*
+let the program exit if it's the only socket left (the default behavior). If
+the socket is `ref`d calling `ref` again will have no effect.
+
 ### socket.remoteAddress
 
 The string representation of the remote IP address. For example,

diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown
@@ -29,3 +29,20 @@ you can also pass arguments to the callback.
 ## clearInterval(intervalId)
 
 Stops a interval from triggering.
+
+## unref()
+
+The opaque value returned by `setTimeout` and `setInterval` also has the method
+`timer.unref()` which will allow you to create a timer that is active but if
+it is the only item left in the event loop won't keep the program running.
+If the timer is already `unref`d calling `unref` again will have no effect.
+
+In the case of `setTimeout` when you `unref` you create a separate timer that
+will wakeup the event loop, creating too many of these may adversely effect
+event loop performance -- use wisely.
+
+## ref()
+
+If you had previously `unref()`d a timer you can call `ref()` to explicitly
+request the timer hold the program open. If the timer is already `ref`d calling
+`ref` again will have no effect.