Skip to content
Snippets Groups Projects
  • Sergey Kaplun's avatar
    fa38d017
    box: introduce c_func_iproto_multireturn in compat · fa38d017
    Sergey Kaplun authored
    With this option enabled (new), the multiresults returned by a stored C
    function via iproto aren't wrapped in the additional msgpack array (old).
    
    Due to new behaviour some renames are performed:
    * `port_c_dump_msgpack()` -> `port_c_dump_msgpack_wrapped()`, since this
      is dump format with additional msgpack array encoded.
    * `port_c_dump_msgpack16()` -> `port_c_dump_msgpack()`, since this
      format is now the default new format of a msgpack dump.
    
    The behaviour of the C port msgpack dumping depends on the
    `c_func_iproto_multireturn` option:
    * uses `port_c_dump_msgpack()` if set to true (new),
    * uses `port_c_dump_msgpack_wrapped()` otherwise (old).
    
    Needed for #4799
    
    @TarantoolBot document
    Title: Document `c_func_iproto_multireturn` compat option
    
    Please create a documentation page for the new compat option:
    https://tarantool.io/compat/c_func_iproto_multireturn
    
    In the new behaviour, the multiresults returned by a stored C function
    via iproto aren't wrapped in the additional msgpack array (old).
    
    ```
    tarantool> compat.c_func_iproto_multireturn = 'old'
    ---
    ...
    
    tarantool> net_box.connect(box.cfg.listen):call('myclib.cfunc')
    ---
    - [true, -1]
    ...
    
    tarantool> compat.c_func_iproto_multireturn = 'new'
    ---
    ...
    
    tarantool> net_box.connect(box.cfg.listen):call('myclib.cfunc')
    ---
    - true
    - -1
    ...
    
    ```
    
    The new behaviour is consistent with the local call of the function
    via `box.func`:
    
    ```
    tarantool> box.func['myclib.cfunc']:call()
    ---
    - true
    - -1
    ...
    
    ```
    
    Assume you have a stored C function that returns values like the
    following:
    
    ```c
    char *position = mp_encode_bool(buffer, true);
    box_return_mp(ctx, buffer, position);
    /* ... */
    position = mp_encode_int(buffer, -1);
    box_return_mp(ctx, buffer, position);
    ```
    
    If you want to preserve the format of the returned array for your C
    functions, when the `c_func_iproto_multireturn` option is set to "new",
    you should add the additional wrapping, like the following:
    
    ```c
    char *position = mp_encode_array(buffer_with_results, n_results);
    position = mp_encode_bool(position, true);
    /* ... */
    position = mp_encode_int(position, -1);
    box_return_mp(ctx, buffer_with_results, position);
    ```
    
    The amount of `box_return_mp()` calls indicates the number of values to
    be returned.
    
    Also, you should update its usage via `box.func` if there is any.
    
    (cherry picked from commit 96ee6d9b)
    fa38d017
    History
    box: introduce c_func_iproto_multireturn in compat
    Sergey Kaplun authored
    With this option enabled (new), the multiresults returned by a stored C
    function via iproto aren't wrapped in the additional msgpack array (old).
    
    Due to new behaviour some renames are performed:
    * `port_c_dump_msgpack()` -> `port_c_dump_msgpack_wrapped()`, since this
      is dump format with additional msgpack array encoded.
    * `port_c_dump_msgpack16()` -> `port_c_dump_msgpack()`, since this
      format is now the default new format of a msgpack dump.
    
    The behaviour of the C port msgpack dumping depends on the
    `c_func_iproto_multireturn` option:
    * uses `port_c_dump_msgpack()` if set to true (new),
    * uses `port_c_dump_msgpack_wrapped()` otherwise (old).
    
    Needed for #4799
    
    @TarantoolBot document
    Title: Document `c_func_iproto_multireturn` compat option
    
    Please create a documentation page for the new compat option:
    https://tarantool.io/compat/c_func_iproto_multireturn
    
    In the new behaviour, the multiresults returned by a stored C function
    via iproto aren't wrapped in the additional msgpack array (old).
    
    ```
    tarantool> compat.c_func_iproto_multireturn = 'old'
    ---
    ...
    
    tarantool> net_box.connect(box.cfg.listen):call('myclib.cfunc')
    ---
    - [true, -1]
    ...
    
    tarantool> compat.c_func_iproto_multireturn = 'new'
    ---
    ...
    
    tarantool> net_box.connect(box.cfg.listen):call('myclib.cfunc')
    ---
    - true
    - -1
    ...
    
    ```
    
    The new behaviour is consistent with the local call of the function
    via `box.func`:
    
    ```
    tarantool> box.func['myclib.cfunc']:call()
    ---
    - true
    - -1
    ...
    
    ```
    
    Assume you have a stored C function that returns values like the
    following:
    
    ```c
    char *position = mp_encode_bool(buffer, true);
    box_return_mp(ctx, buffer, position);
    /* ... */
    position = mp_encode_int(buffer, -1);
    box_return_mp(ctx, buffer, position);
    ```
    
    If you want to preserve the format of the returned array for your C
    functions, when the `c_func_iproto_multireturn` option is set to "new",
    you should add the additional wrapping, like the following:
    
    ```c
    char *position = mp_encode_array(buffer_with_results, n_results);
    position = mp_encode_bool(position, true);
    /* ... */
    position = mp_encode_int(position, -1);
    box_return_mp(ctx, buffer_with_results, position);
    ```
    
    The amount of `box_return_mp()` calls indicates the number of values to
    be returned.
    
    Also, you should update its usage via `box.func` if there is any.
    
    (cherry picked from commit 96ee6d9b)