Attach to an existing buffer and receive a pipe of updates pretaining to this buffer.

The opts parameter is currently unused but may become used by neovim in the future.

This function returns a regular Deferred.t instead of an api_call because it is impossible to execute atomically -- due to potential race conditions between multiple attaches and detaches, this function is written as multiple api calls to neovim that are sequenced according to Throttle.Sequencer. This has the side effect of potentially running Async cycles during execution, which may in turn invoke other neovim operations, violating the atomicity guarantee of Api_call.

Attaching to a buffer is unlikely to race with anything. The only operation that may interfere with the buffer attach is if the buffer is deleted or otherwise stops broadcasting while the attach is in flight. Depending on the exact ordering, then, one of two things may happen:

• If the delete occurs before the attach completes, then the attach will fail with a ``nonexistent buffer'' error.
• If the attach completes first, then it will receive a detach message immediately and close itself.

Both cases are ones the application should be prepared to handle.

nvim_buf_detach isn't directly exposed because it would detach all attached clients. Instead, simply close the returned pipe.