This page describes the asynchronous C++ mapping for the ice_invoke proxy function and the Blobject class.
On this page:
Calling ice_invoke Asynchronously in C++
The asynchronous mapping for ice_invoke resembles the AMI mapping. The return value and the parameters operation, mode, and inParams have the same semantics as for the synchronous version of ice_invoke.
Proxy member functions
// "future" async function
// with P = std::promise (the default), it returns a std::future<Ice::Object::Ice_invokeResult>
//
template<template<typename> class P = std::promise> auto
ice_invokeAsync(const std::string& operation,
Ice::OperationMode mode,
const std::vector<Byte>& inP,
const ::Ice::Context& context = Ice::noExplicitContext)
-> decltype(std::declval<P<Ice::Object::Ice_invokeResult>>().get_future());
// async function with callbacks
//
std::function<void()>
ice_invokeAsync(const std::string& operation,
Ice::OperationMode mode,
const std::vector<Ice::Byte>& inP,
std::function<void(bool, const std::vector<Ice::Byte>&)> response,
std::function<void(std::exception_ptr)> ex = nullptr,
std::function<void(bool)> sent = nullptr,
const Ice::Context& context = Ice::noExplicitContext);
// "future" async function, with "zero-copy" in parameter
// with P = std::promise (the default), it returns a std::future<Ice::Object::Ice_invokeResult>
//
template<template<typename> class P = std::promise> auto
ice_invokeAsync(const std::string& operation,
Ice::OperationMode mode,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inP,
const Ice::Context& context = Ice::noExplicitContext)
-> decltype(std::declval<P<Ice::Object::Ice_invokeResult>>().get_future());
// async function with callbacks, and "zero-copy" in parameter
//
std::function<void()>
ice_invokeAsync(const std::string& operation,
Ice::OperationMode mode,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inP,
std::function<void(bool, const std::pair<const Ice::Byte*, const Ice::Byte*>&)> response,
std::function<void(std::exception_ptr)> ex = nullptr,
std::function<void(bool)> sent = nullptr,
const Ice::Context& context = Ice::noExplicitContext);
Ice::Object
class Object
{
public:
...
struct Ice_invokeResult
{
bool returnValue;
std::vector<Ice::Byte> outParams;
};
};
Proxy member functions
// Basic (no callback)
//
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::vector<Ice::Byte>& inParams);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::vector<Ice::Byte>& inParams,
const Ice::Context& context);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inParams);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inParams,
const Ice::Context& context,
const Ice::LocalObjectPtr& cookie = 0);
bool end_ice_invoke(std::vector<Ice::Byte>&, const Ice::AsyncResultPtr&);
// With generic callback - use Ice::newCallback to create these generic callbacks
//
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::vector<Ice::Byte>& inParams,
const:Ice::CallbackPtr& del,
const Ice::LocalObjectPtr& cookie = 0);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::vector<Ice::Byte>& inParams,
const Ice::Context& context,
const Ice::CallbackPtr& del,
const Ice::LocalObjectPtr& cookie = 0);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inParams,
const Ice::CallbackPtr& del,
const Ice::LocalObjectPtr& cookie = 0);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inParams,
const Ice::Context& context,
const Ice::CallbackPtr& del,
const Ice::LocalObjectPtr& cookie = 0);
// With type-safe callback - use newCallback_Object_ice_invoke (below) to create these callbacks
//
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::vector<Ice::Byte>& inParams,
const Ice::Callback_Object_ice_invokePtr& del,
const Ice::LocalObjectPtr& cookie = 0);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::vector<Ice::Byte>& inParams,
const Ice::Context& context,
const Ice::Callback_Object_ice_invokePtr& del,
const Ice::LocalObjectPtr& cookie = 0);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inParams,
const Ice::Callback_Object_ice_invokePtr& del,
const Ice::LocalObjectPtr& cookie = 0);
Ice::AsyncResultPtr begin_ice_invoke(const std::string& op,
Ice::OperationMode mode,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inParams,
const Ice::Context& context,
const Ice::Callback_Object_ice_invokePtr& del,
const Ice::LocalObjectPtr& cookie = 0);
// factory functions for type-safe callbacks
// Versions are provided to support zero-copy semantics for the byte sequence containing the operation's results,
// as well as a cookie value whose type is inferred and represented here by the CT (cookie type) symbol
//
template<class T> Callback_Object_ice_invokePtr
newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance,
void (T::*cb)(bool, const std::vector<Ice::Byte>&),
void (T::*excb)(const Ice::Exception&),
void (T::*sentcb)(bool) = 0);
template<class T> Callback_Object_ice_invokePtr
newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance,
void (T::*cb)(bool, const std::pair<const Ice::Byte*, const Ice::Byte*>&),
void (T::*excb)(const Ice::Exception&),
void (T::*sentcb)(bool) = 0);
template<class T, typename CT> Callback_Object_ice_invokePtr
newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance,
void (T::*cb)(bool, const std::vector<Ice::Byte>&, const CT&),
void (T::*excb)(const Ice::Exception&, const CT&),
void (T::*sentcb)(bool, const CT&) = 0);
template<class T, typename CT> Callback_Object_ice_invokePtr
newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance,
void (T::*cb)(bool, const std::pair<const Ice::Byte*, const Ice::Byte*>&,
const CT&),
void (T::*excb)(const Ice::Exception&, const CT&),
void (T::*sentcb)(bool, const CT&) = 0);
template<class T> Callback_Object_ice_invokePtr
newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance,
void (T::*excb)(const Ice::Exception&),
void (T::*sentcb)(bool) = 0);
template<class T, typename CT> Callback_Object_ice_invokePtr
newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance,
void (T::*excb)(const Ice::Exception&, const CT&),
void (T::*sentcb)(bool, const CT&) = 0);
Subclassing BlobjectAsync in C++
BlobjectAsync is the name of an AMD version of Blobject:
namespace Ice
{
class BlobjectAsync : public virtual Ice::Object
{
public:
virtual void ice_invokeAsync(std::vector<Byte> inParams,
std::function<void(bool, const std::vector<Byte>&)> response,
std::function<void(std::exception_ptr)> eptr,
const Ice::Current& current) = 0;
}
}
You need to create a servant class derived from BlobjectAsync, and override ice_invokeAsync.
Upon a successful invocation, the servant must call response, passing true as the first argument and the encapsulated operation result into the second argument. The servant calls response with false as the first argument to report a user exception; the second argument is then the encapsulated user exception.
The eptr function is used to report Ice run-time exceptions and other (non-Ice) C++ exceptions. If you accidentally report a user exception with this function, the caller will receive a UnknownUserException.
namespace Ice
{
class BlobjectAsync : public virtual Ice::Object
{
public:
virtual void ice_invoke_async(const AMD_Object_ice_invokePtr& cb,
const std::vector<Ice::Byte>& inParams,
const Ice::Current& current) = 0;
}
}
You need to create a class derived from BlobjectAsync, and override ice_invoke_async. The first argument to the servant's member function is a callback object of type Ice::AMD_Object_ice_invoke, shown here:
namespace Ice
{
class AMD_Object_ice_invoke : ...
{
public:
virtual void ice_response(bool result, const std::vector<Ice::Byte>& outParams) = 0;
virtual void ice_response(bool result, const std::pair<const Ice::Byte*, const Ice::Byte*>& outParams) = 0;
virtual void ice_exception(const std::exception&) = 0;
virtual void ice_exception() = 0;
}
}
Upon a successful invocation, the servant must call ice_response, passing true as the first argument and the encapsulated operation result into the second argument. The servant calls ice_response with false as the first argument to report a user exception; the second argument is then the encapsulated user exception.
ice_exception is used to report Ice run-time exceptions and other (non-Ice) standard C++ exceptions. If you accidentally report a user exception with ice_exception, the caller will receive a UnknownUserException.
Subclassing BlobjectArrayAsync in C++
BlobjectArrayAsync is just like BlobjectAsync (described above), except we use the array mapping to pass the in parameters:
namespace Ice
{
class BlobjectArrayAsync : public virtual Object
{
public:
virtual void ice_invokeAsync(std::pair<const Ice::Byte*, const Ice::Byte*> inParams,
std::function<void(bool, const std::pair<const Ice::Byte*, const Ice::Byte*>&)> response,
std::function<void(std::exception_ptr)> eptr,
const Ice::Current& current) = 0;
}
}
namespace Ice
{
class BlobjectArrayAsync : public virtual Object
{
public:
virtual void ice_invoke_async(const Ice:AMD_Object_ice_invokePtr& cb,
const std::pair<const Ice::Byte*, const Ice::Byte*>& inParams,
const Ice::Current& current) = 0;
}
}