Old triggers API enhancements

Related dev. issues: https://github.com/tarantool/tarantool/issues/8659, https://github.com/tarantool/tarantool/issues/6484

Product: Tarantool
Since: 3.0.0
Root document: https://www.tarantool.io/en/doc/latest/concepts/triggers/
SME: @ drewdzzz
https://www.tarantool.io/en/doc/latest/release/3.0.0/#triggers
https://habr.com/ru/companies/vk/articles/782318/

Old trigger API enhancements

Any callable object

Previously, only function could be set as a trigger. Now, any callable object is supported.

Named triggers

Now, every trigger has a unique name. It can be passed as the third argument.

If the name is not passed, address of handler is considered as a name - the old behavior is simulated.
When the name is passed, second argument is ignored:

1. If the new trigger is not nil, the new trigger is set by name or an existing one with this name is replaced.
2. If the new trigger is nil, the trigger is removed by name (no-op if it doesn't exist).

Example:

-- Set f1 by name
space:on_replace(f1, nil, "my_trigger")
-- Replace f1 with f2
space:on_replace(f2, nil, "my_trigger")

Let's pass second argument now:

-- Set f1 with its address as name
space:on_replace(f1)
-- Set f2 by name "my_trigger"
-- The second argument is ignored - f1 is not removed
space:on_replace(f2, f1, "my_trigger")

Old way, without name:

-- Set f1 with its address as name
space:on_replace(f1)
-- Set f2 with its address as name, f1 is removed.
space:on_replace(f2, f1)

Unique unnamed triggers

Since every trigger has a unique name, you cannot set one handler twice without a name:

-- Set f1 with its address as name
space:on_replace(f1)
-- Set f1 with its address as name
-- Since the name is unique, nothing has changed
space:on_replace(f1)

Key-value API

The old API was extended solely for the purpose of backward compatibility. We've introduced another API, and we recommend to use it instead of the old one.

Now triggers can be set with key-value API. It accepts two arguments: func and name. Name must not be nil. If func is nil, the trigger is removed by name, or no-op if there is no such trigger. If func is not nil, it must be a callable object - it is set as a trigger by passed name.

Example:

-- Set f1
space:on_replace{func=f1, name="my_trigger"}
-- Replace f1 with f2
space:on_replace{func=f2, name="my_trigger"}
-- Remove f2
space:on_replace{name="my_trigger"}

SWIM triggers

There are slightly different swim triggers - they accept ctx as well.

Now it accepts four arguments:

1. new_trigger
2. old_trigger or ctx - is considered as old_trigger if object is callable.
3. trigger_name or ctx - is considered as trigger_name if object is string.
4. ctx or nil

Also, ctx can be passed with key-value trigger API using key "ctx".

See the test for examples.

Start with the linked triggers root document and compare its old trigger API coverage with the enhancements described in this issue. Use test/box-luatest/triggers_old_api_test.lua, especially the cited section, to verify the documented callable objects, named and key-value APIs, uniqueness behavior, and SWIM context arguments; done means the documentation reflects these examples and behaviors.