Deprecate msgpack.ibuf_decode

[locker]

Mark msgpack.ibuf_decode as deprecated. Recommend using msgpack.decode or msgpack.decode_unchecked instead.

See: tarantool/tarantool#2755

[lenkis]

This should go to both 1.7 and 1.8 doc branches.
Peter, please add to 1.7, and I'll merge it further to 1.8.

[Totktonada]

The new function variants that accept a string buffer were introduced in tarantool/tarantool#2755: that is the reason of deprecation of the separate msgpack.ibuf_decode function. The new variants should be described in the website documentation. Now the documentation lacks it.

The linked issue has great formal description of the new API. It would be good to have it on the website.

[pgulutzan]

The 1.10 documentation lacks description of some functions that are in the 2.2 documentation; Are those the functions that are supposed to be described? If so, perhaps long ago I pushed a change to the wrong version.

[pgulutzan]

There was no reply, and the changes have been copied to the 1.10 documentation, so I have removed the "need feedback" tag and am closing this issue.

[Totktonada]

Sorry for reopening this again, but encode / decode / decode_unchecked variants, which reads from or writes to a char * buffer, are not described in the docs. See tarantool/tarantool@68c2139

[pgulutzan]

I looked at the version-2.4 decode_unchecked documentation, here:
https://www.tarantool.io/en/doc/2.4/reference/reference_lua/msgpack/#msgpack-decode-unchecked
I clicked on the word "buffer" in the sentence "For an example see the buffer module."
I ran the example there, which includes decode_unchecked.
The result is what the manual describes (at least in 2.4).
So I am trying to understand why, although it is described in the docs, it is not found.
Perhaps my mistake is that I did not properly link, or did not properly explain when I closed?

[Totktonada]

Several points:

• encode() may accept a buffer (buffer.ibuf() kind) as the second argument. Note also that it returns number of written bytes in the case, not a Lua string with encoded msgpack data.

• decode() may accept a buffer (cdata<char *> kind) as the first argument and it also changes meaning of the second argument (it becomes the buffer size).

• Re decode_unchecked(): cdata<char *> or cdata<const char *> is not string. They are different types in Lua. So current description can be confusing for users.

• Cite:

  Because checking is skipped, decode_unchecked() can operate with string pointers to buffers which decode() cannot handle.

  I would not say that support of char * is consequence of lack of buffer bounds checks.

[Totktonada]

(@pgulutzan Feel free to ask me details here or privately if something is not clear or if you think that I missed something.)

[pgulutzan]

@Toktonada: Thank you. I made several changes to the version 2.4 manual, but won't close if you think it is still not done.

[Totktonada]

.. function:: decode_unchecked(C_style_string_pointer[, size])
Input and output are the same as for
:ref:decode(C_style_string_pointer) <msgpack-decode_c_style_string_pointer>,
except that size is optional.

decode_unchecked() with C-style-pointed (cdata first argument) does not check size at all (even if it passed). I think we should not see optional size in the function arguments.

How to verify:

tarantool> msgpack = require('msgpack')
tarantool> ffi = require('ffi')
tarantool> msgpack.decode(ffi.cast('char *', '\x91\x00'), 1)
---
- error: 'msgpack.decode: invalid MsgPack'
...

tarantool> msgpack.decode_unchecked(ffi.cast('char *', '\x91\x00'), 1)
---
- [0]
- 'cdata<char *>: 0x40eb9d82'
...

Except this, I don't have objections. Please, update all versions and close the issue finally.

[pgulutzan]

Okay, changes pushed in 2.4, 2.3, 2.2, and 1.10.

[Totktonada]

Thank you, Peter!