@@ -328,6 +328,25 @@ getSelfNode = localNodeId . processNode <$> ask
328328
329329-- | Link to a remote process (asynchronous)
330330--
331+-- When process A links to process B (that is, process A calls
332+-- @link pidB@) then an asynchronous exception will be thrown to process A
333+-- when process B terminates (normally or abnormally), or when process A gets
334+-- disconnected from process B. Although it is /technically/ possible to catch
335+-- these exceptions, chances are if you find yourself trying to do so you should
336+-- probably be using 'monitor' rather than 'link'. In particular, code such as
337+--
338+-- > link pidB -- Link to process B
339+-- > expect -- Wait for a message from process B
340+-- > unlink pidB -- Unlink again
341+--
342+-- doesn't quite do what one might expect: if process B sends a message to
343+-- process A, and /subsequently terminates/, then process A might or might not
344+-- be terminated too, depending on whether the exception is thrown before or
345+-- after the 'unlink' (i.e., this code has a race condition).
346+--
347+-- Linking is all-or-nothing: A is either linked to B, or it's not. A second
348+-- call to 'link' has no effect.
349+--
331350-- Note that 'link' provides unidirectional linking (see 'spawnSupervised').
332351-- Linking makes no distinction between normal and abnormal termination of
333352-- the remote process.
@@ -335,6 +354,17 @@ link :: ProcessId -> Process ()
335354link = sendCtrlMsg Nothing . Link . ProcessIdentifier
336355
337356-- | Monitor another process (asynchronous)
357+--
358+-- When process A monitors process B (that is, process A calls
359+-- @monitor pidB@) then process A will receive a 'ProcessMonitorNotification'
360+-- when process B terminates (normally or abnormally), or when process A gets
361+-- disconnected from process B. You receive this message like any other (using
362+-- 'expect'); the notification includes a reason ('DiedNormal', 'DiedException',
363+-- 'DiedDisconnect', etc.).
364+--
365+-- Every call to 'monitor' returns a new monitor reference 'MonitorRef'; if
366+-- multiple monitors are set up, multiple notifications will be delivered
367+-- and monitors can be disabled individually using 'unmonitor'.
338368monitor :: ProcessId -> Process MonitorRef
339369monitor = monitor' . ProcessIdentifier
340370