DRTVWR-558: Clean up LLEventDispatcher argument and result handling.

Add a new LLEventDispatcher constructor accepting not only the map key to
extract a requested function name, but a second map key to extract the
arguments -- when required.

In Doxygen comments, clarify the difference between the two constructors.

Move interaction with the LLEventPump subsystem to LLDispatchListener.
LLEventDispatcher is intended to be directly called. On error, instead of
looking for a "reply" key in the invocation LLSD, throw DispatchError.

Publish DispatchError, formerly an implementation detail, and its new subclass
DispatchMissing.

Make both LLEventDispatcher::operator()() overloads return LLSD, leveraging
the new internal ReturnLLSD logic that returns a degenerate LLSD blob for a
void target callable and, for compatible types, converts the returned value to
LLSD. Notably, the public try_call() overloads still return bool; any value
returned by the target callable is discarded.

Clarify the operator() and try_call() argument requirements for target
callables registered to accept an LLSD array, in Doxygen comments and in code.
In particular, the 'event' passed to (event) overloads (vs. the (name, event)
overloads) must be an LLSD map, so it must contain an "args" key (or the new
arguments map key specified to the constructor) containing the LLSD args
array.

Since the use of the new args key depends on whether the target callable is
registered to accept an array or a map, pass it into DispatchEntry::call()
(and all subclass overrides), along with a bool to disambiguate whether we
reached that method from an LLEventDispatcher (event) invocation method or a
(name, event) invocation method.

Allow streaming an LLEventDispatcher instance to std::ostream, primarily to
facilitate construction of proper error messages.

Revert the 'name' argument of internal try_call(key, name, event) to
std::string. Ditch try_call_log(), try_call_one() and reply(). Fold
try_call_one() logic into three-argument try_call().

Refactor callFail() as a template method accepting both the exception to throw
and arbitrary stringize() arguments from which to construct the exception
message. Non-static callFail() implicitly prepends the instance and a colon to
the rest of the arguments, and calls static sCallFail(). The latter constructs
the exception message, logs it and throws the specified exception. This
obviates try_call_log().

Make implementation detail helper class LLSDArgsMapper a private member of
LLEventDispatcher so it can access sCallFail(): we now want all error handling
to go through that method. Add LLSDArgsMapper::callFail() resembling
LLSDEventDispatcher::callFail(), but without having to specify the exception:
only LLEventDispatcher will throw anything but generic DispatchError.

Give LLEventDispatcher::ParamsDispatchEntry and its subclasses
ArrayParamsDispatchEntry and MapParamsDispatchEntry a new 'name' argument to
identify error messages. Store it and use it implicitly in new callFail()
method, very like LLSDArgsMapper::callFail(). Make LLEventDispatcher::
addArrayParamsDispatchEntry() and addMapParamsDispatchEntry() pass a 'name'
that includes the LLEventDispatcher instance name as well as the name of the
specific registered callable. This way we need not intercept a low-level error
and annotate it with contextual data: we can just let the exception propagate.

Make ParamsDispatchEntry::call() override catch LL::apply_error thrown by an
invoker_function, and pass its message to callFail(), i.e. rethrow as
LLEventDispatcher::DispatchError.

Introduce ArrayParamsDispatchEntry::call() override for the special logic to
extract an arguments array from a passed LLSD map -- but only under the
circumstances described in the Doxygen comment.

Add similar logic to MapParamsDispatchEntry::call(), but with both argskey
itself and a value for argskey optional in the passed LLSD map.

Because LLEventDispatcher now has two constructor overloads, allow subclass
constructor LLDispatchListener() to accept zero or more trailing arguments.
This is different than giving LLDispatchListener's constructor a default final
argument, in that the subclass doesn't need to specify its default value:
that's up to the base-class constructor. But it does require that the subclass
constructor move to the header file.

Move private LLEventDispatcher::reply() method to LLDispatchListener. Extend
LLDispatchListener::process() to handle DispatchError by attempting to reply
with a map containing an "error" key, per convention. (In other words, move
that logic from LLEventDispatcher to LLDispatchListener.) Also, for a map LLSD
result, attempt to reply with that result; for other defined LLSD types,
attempt to reply with a map containing a "data" key. This is backwards
compatible with previous behavior because all previous LLDispatchListener
subclass methods returned void, which now produces an undefined LLSD blob,
which we don't bother trying to send in reply.

In lleventdispatcher_test.cpp, rework tut::lleventdispatcher_data::call_exc()
yet again to catch DispatchError instead of listening for an LLEventPump reply
event. Similarly, make call_logerr() catch DispatchError. Since the exception
should also be logged, we ignore it and focus on the log, as before.

Add tests <23> to <27>, exercising calls to new class DispatchResult methods
returning string, int, LLSD map, LLSD array and void.

(cherry picked from commit 2f9c915dd3d5137b5b2b1a57f0179e1f7a090f8c)

0 files changed, 0 insertions, 0 deletions