From 75205a75314c219cbfcd12ef29c01707f3641876 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 20 Dec 2024 13:54:00 +0700 Subject: [PATCH] Deprecate box.session.push() (#4695) Resolves #3615 --- .../configuration/configuration_reference.rst | 1 + doc/reference/reference_capi/box.rst | 2 + doc/reference/reference_lua/box_session.rst | 2 +- .../reference_lua/box_session/push.rst | 2 + doc/reference/reference_lua/compat.rst | 2 + .../compat/box_session_push_deprecation.rst | 47 +++++++++++++++++++ 6 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 doc/reference/reference_lua/compat/box_session_push_deprecation.rst diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 70e3adb61e..cfbe740099 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -529,6 +529,7 @@ The ``compat`` section defines values of the :ref:`compat ` modul - ``new``: raise an error - ``old``: do not raise an error + See also: :ref:`compat-option-session-push-deprecation` | | Type: string diff --git a/doc/reference/reference_capi/box.rst b/doc/reference/reference_capi/box.rst index 8aeb69123b..51955a6157 100644 --- a/doc/reference/reference_capi/box.rst +++ b/doc/reference/reference_capi/box.rst @@ -192,6 +192,8 @@ .. c:function:: int box_session_push(const char *data, const char *data_end) + **Deprecated since** :doc:`3.0.0 `. + Since version :doc:`2.4.1 `. Push MessagePack data into a session data channel -- socket, console or whatever is behind the session. Behaves just like Lua diff --git a/doc/reference/reference_lua/box_session.rst b/doc/reference/reference_lua/box_session.rst index 1020273b89..050356bf99 100644 --- a/doc/reference/reference_lua/box_session.rst +++ b/doc/reference/reference_lua/box_session.rst @@ -67,7 +67,7 @@ Below is a list of all ``box.session`` functions and members. - Define a trigger to report restricted actions * - :doc:`./box_session/push` - - Send an out-of-band message + - (Deprecated) Send an out-of-band message .. toctree:: :hidden: diff --git a/doc/reference/reference_lua/box_session/push.rst b/doc/reference/reference_lua/box_session/push.rst index 9823fe231c..cff537b16b 100644 --- a/doc/reference/reference_lua/box_session/push.rst +++ b/doc/reference/reference_lua/box_session/push.rst @@ -10,6 +10,8 @@ box.session.push() .. function:: box.session.push(message [, sync]) + **Deprecated since** :doc:`3.0.0 `. + Generate an out-of-band message. By "out-of-band" we mean an extra message which supplements what is passed in a network via the usual channels. Although ``box.session.push()`` can be called at any time, in diff --git a/doc/reference/reference_lua/compat.rst b/doc/reference/reference_lua/compat.rst index 0f9999acbb..56e3a18621 100644 --- a/doc/reference/reference_lua/compat.rst +++ b/doc/reference/reference_lua/compat.rst @@ -74,6 +74,7 @@ Below are the available ``compat`` options: * :doc:`fiber_slice_default <./compat/fiber_slice_default>` * :doc:`binary_data_decoding <./compat/binary_data_decoding>` * :doc:`box_info_cluster_meaning <./compat/box_info_cluster_meaning>` +* :doc:`box_session_push_deprecation <./compat/box_session_push_deprecation>` .. toctree:: :hidden: @@ -85,4 +86,5 @@ Below are the available ``compat`` options: compat/sql_seq_scan_default compat/fiber_slice_default compat/binary_data_decoding + compat/box_session_push_deprecation compat/compat_tutorial diff --git a/doc/reference/reference_lua/compat/box_session_push_deprecation.rst b/doc/reference/reference_lua/compat/box_session_push_deprecation.rst new file mode 100644 index 0000000000..4557f4c946 --- /dev/null +++ b/doc/reference/reference_lua/compat/box_session_push_deprecation.rst @@ -0,0 +1,47 @@ +.. _compat-option-session-push-deprecation: + +box.session.push() deprecation +============================== + +Option: ``box_session_push_deprecation`` + +Starting from version 3.0, Lua API function :ref:`box.session.push() ` +and C API function :ref:`box_session_push() ` are deprecated. + +Old and new behavior +-------------------- + +New behavior: calling `box.session.push()` raises an error. + +.. code-block:: tarantoolsession + + tarantool> box.session.push({1}) + --- + - error: box.session.push is deprecated + ... + +Old behavior: `box.session.push()` is available to use. When it's called for the +first time, a deprecation warning is printed to the log. + +.. code-block:: tarantoolsession + + tarantool> box.session.push({1}) + 2024-12-18 15:42:51.537 [50750] main/104/interactive session.c:569 W> box.session.push is deprecated. Consider using box.broadcast instead. + %TAG !push! tag:tarantool.io/push,2018 + --- + - 1 + ... + --- + - true + ... + +Known compatibility issues +-------------------------- + +At this point, no incompatible modules are known. + +Detecting issues in your codebase +--------------------------------- + +If your application uses `box.session.push()`, consider rewriting it using +:ref:`box.broadcast() `. \ No newline at end of file