api: deprecate box.session.push() usage

`box.session.push` is deprecated starting from Tarantool 3.0. We are
going to remove the feature from the connector in a next major
release.

Part of #324

Author: oleg-jukovec

CHANGELOG.md

@@ -76,6 +76,8 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release.
 - All ConnectionPool.<Request>, ConnectionPool.<Request>Typed and
   ConnectionPool.<Request>Async methods. Instead you should use requests
   objects + ConnectionPool.Do() (#241)
+- box.session.push() usage: Future.AppendPush() and Future.GetIterator()
+  methods, ResponseIterator and TimeoutResponseIterator types (#324)
 
 ### Removed
 

future.go

@@ -128,6 +128,9 @@ func NewFuture() (fut *Future) {
 
 // AppendPush appends the push response to the future.
 // Note: it works only before SetResponse() or SetError()
+//
+// Deprecated: the method will be removed in the next major version,
+// use Connector.NewWatcher() instead of box.session.push().
 func (fut *Future) AppendPush(resp *Response) {
 	fut.mutex.Lock()
 	defer fut.mutex.Unlock()
@@ -208,6 +211,9 @@ func (fut *Future) GetTyped(result interface{}) error {
 //
 //   - box.session.push():
 //     https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_session/push/
+//
+// Deprecated: the method will be removed in the next major version,
+// use Connector.NewWatcher() instead of box.session.push().
 func (fut *Future) GetIterator() (it TimeoutResponseIterator) {
 	futit := &asyncResponseIterator{
 		fut: fut,

response_it.go

@@ -5,6 +5,9 @@ import (
 )
 
 // ResponseIterator is an interface for iteration over a set of responses.
+//
+// Deprecated: the method will be removed in the next major version,
+// use Connector.NewWatcher() instead of box.session.push().
 type ResponseIterator interface {
 	// Next tries to switch to a next Response and returns true if it exists.
 	Next() bool
@@ -16,6 +19,9 @@ type ResponseIterator interface {
 
 // TimeoutResponseIterator is an interface that extends ResponseIterator
 // and adds the ability to change a timeout for the Next() call.
+//
+// Deprecated: the method will be removed in the next major version,
+// use Connector.NewWatcher() instead of box.session.push().
 type TimeoutResponseIterator interface {
 	ResponseIterator
 	// WithTimeout allows to set up a timeout for the Next() call.