Permalink
Browse files

add docs for socket/server/timer unref and ref

  • Loading branch information...
tjfontaine authored and piscisaureus committed Jul 13, 2012
1 parent cd6122e commit bdd1a740cb5029860a2eef20d8e9814f378d99c4
Showing with 53 additions and 0 deletions.
  1. +12 −0 doc/api/dgram.markdown
  2. +24 −0 doc/api/net.markdown
  3. +17 −0 doc/api/timers.markdown
View
@@ -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.
View
@@ -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,
View
@@ -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.

0 comments on commit bdd1a74

Please sign in to comment.