api: add events subscription support

[oleg-jukovec]

A user can create watcher by the Connection.NewWatcher() call:

    watcher = conn.NewWatcker("key", func(event WatchEvent) {
        // The callback code.
    })

After that, the watcher callback is invoked for the first time. In this case, the callback is triggered whether or not the key has already been broadcast. All subsequent invocations are triggered with box.broadcast() called on the remote host. If a watcher is subscribed for a key that has not been broadcast yet, the callback is triggered only once, after the registration of the watcher.

If the key is updated while the watcher callback is running, the callback will be invoked again with the latest value as soon as it returns.

Multiple watchers can be created for one key.

If you don’t need the watcher anymore, you can unregister it using the Unregister method:

    watcher.Unregister()

The api is similar to net.box implementation [1].

It also adds a BroadcastRequest to make it easier to send broadcast messages.

1. https://www.tarantool.io/en/doc/latest/reference/reference_lua/net_box/#conn-watch

I didn't forget about (remove if it is not applicable):

• Tests (see documentation for a testing package)
• Changelog (see documentation for changelog format)
• Documentation (see documentation for documentation style guide)

Related issues:

Closes #119

[oleg-jukovec]

There are few things to do after #226 will be merged into master:

1. Rebase Connection.writeRequest() implementation in connection.go .
2. Add feature check into Connection.NewWatcher() call (I left TODO in the place).
3. Add feature check into ConnectionPool.NewWatcher() call (I left TODO in the place).

But it doesn't look critical and can be done quickly. This will not affect the idea of the pull request.

[DifferentialOrange]

1. https://www.tarantool.io/ru/doc/latest/reference/reference_lua/net_box/#conn-watch

It is better to refer to /en/ documentation.

[DifferentialOrange]

I've try to review it one more time later. It's rather hard to catch on all these concurrency details from the first time (especially if you're not familiar with them).

[oleg-jukovec]

I've try to review it one more time later. It's rather hard to catch on all these concurrency details from the first time (especially if you're not familiar with them).

Thank you! I could recommend to review in this order:

1. Connection.
2. ConnectionMulti.
3. ConnectionPool.

It would be possible to split the commit into several (Connection, ConnectionMulti, ConnectionPool, Connector), but it look like a single feature, so I did not do it.

[better0fdead]

Hello, thx for patch. I am generally ok, just some small comments.

[DifferentialOrange]

If a watcher is subscribed for a key that has not been broadcast yet, the callback is triggered only once

I'm still a bit confused. If a watcher subscribed for a key that has been broadcasted before the subscription, will callback be triggered twice? If yes, with which values? Or will it be triggered for each historical value in their order? Or will it trigger only once for the current key value? If yes, I don't get what "If a watcher is subscribed for a key that has not been broadcast yet, the callback is triggered only once" should mean since they all are triggered only once on bootstrap.

[oleg-jukovec]

Or will it trigger only once for the current key value? If yes, I don't get what "If a watcher is subscribed for a key that has not been broadcast yet, the callback is triggered only once" should mean since they all are triggered only once on bootstrap.

It is copy-paste from: https://www.tarantool.io/ru/doc/latest/reference/reference_lua/box_events/#how-a-watcher-works

I think I need to look at the whole paragraph. The last sentence explains what will happen if there are no broadcasts yet. But I can delete the sentence =)