NamedInstance

NamedInstance#

template<typename InstanceType> class NamedInstance#

Named instance that can invoke the Function method of this class to construct member functions of the instance’s class, suitable for object-oriented programming scenarios.

Template Parameters:: InstanceType – The type of the instance.

Public Functions

template<typename F> InstanceFunctionHandler<F, InstanceType> Function(F memberFunc)#

Constructs a Function for a named instance’s function call, preparing to execute the function.

auto counter = YR::Instance(Counter::FactoryCreate, "name_1").Invoke(100);
auto c = counter.Function(&Counter::Add).Invoke(1);
std::cout << "counter is " << *YR::Get(c) << std::endl;

Template Parameters:: F – The type of the member function.
Parameters:: memberFunc – The function to be executed within the instance. If the instance is bound to a class object, the function must be a member function of the class.
Returns:: An instance of the InstanceFunctionHandler class, which provides member methods for executing the function call.

template<typename R> InstanceFunctionHandler<CppClassMethod<R>, InstanceType> CppFunction(const std::string &functionName)#

Sends a request to invoke a C++ class member function to a remote backend, which executes the user function call.

class Counter {
public:
    int count;

    Counter() {}

    explicit Counter(int init) : count(init) {}

    static Counter *FactoryCreate()
    {
        int c = 10;
        return new Counter(c);
    }

    std::string RemoteVersion()
    {
        return "RemoteActor v0";
    }
};

YR_INVOKE(Counter::FactoryCreate, &Counter::RemoteVersion)

int main(void)
{
    YR::Config conf;
    YR::Init(conf);

    auto cppCls = YR::CppInstanceClass::FactoryCreate("Counter::FactoryCreate");
    auto cppIns = YR::Instance(cppCls).Invoke();
    auto obj = cppIns.CppFunction<std::string>("&Counter::RemoteVersion").Invoke();
    auto res = *YR::Get(obj);
    std::cout << "add one result is " << res << std::endl;
    return 0;
}

Template Parameters:: R – The return type of the function.
Parameters:: functionName – The name of the C++ class member function.
Returns:: An InstanceFunctionHandler object, which can be used to invoke the instance by calling its Invoke member function.

template<typename R> InstanceFunctionHandler<PyClassMethod<R>, InstanceType> PyFunction(const std::string &functionName)#

Sends a request to invoke a Python class member function to a remote backend, which executes the user function call.

int main(void)
{
    // class Instance:
    //     sum = 0
    //
    //     def __init__(self, init):
    //       self.sum = init
    //
    //     def add(self, a):
    //       self.sum += a
    //
    //     def get(self):
    //       return self.sum
    YR::Config conf;
    YR::Init(conf);

    auto pyInstance = YR::PyInstanceClass::FactoryCreate("pycallee", "Instance");  // moduleName, className
    auto r1 = YR::Instance(pyInstance).Invoke(x);
    r1.PyFunction<void>("add").Invoke(1);  // returnType, memberFunctionName

    auto r2 = r1.PyFunction<int>("get").Invoke();
    auto res = *YR::Get(r2);

    std::cout << "PlusOneWithPyClass with result=" << res << std::endl;
    return res;

    return 0;
}

Template Parameters:: R – The return type of the function.
Parameters:: functionName – The name of the Python class member function.
Returns:: An InstanceFunctionHandler object, which can be used to invoke the instance by calling its Invoke member function.

template<typename R> InstanceFunctionHandler<JavaClassMethod<R>, InstanceType> JavaFunction(const std::string &functionName)#

Sends a request to invoke a Java class member function to a remote backend, which executes the user function call.

int main(void)
{
    // package io.yuanrong.demo;
    //
    // // A regular Java class.
    // public class Counter {
    //
    //     private int value = 0;
    //
    //     public int increment() {
    //         this.value += 1;
    //         return this.value;
    //     }
    // }
    YR::Config conf;
    YR::Init(conf);
    auto javaInstance = YR::JavaInstanceClass::FactoryCreate("io.yuanrong.demo.Counter");
    auto r1 = YR::Instance(javaInstance).Invoke();
    auto r2 = r1.JavaFunction<int>("increment").Invoke(1);
    auto res = *YR::Get(r2);
    std::cout << "PlusOneWithJavaClass with result=" << res << std::endl;
    return res;
}

Template Parameters:: R – The return type of the function.
Parameters:: functionName – The name of the Java class member function.
Returns:: An InstanceFunctionHandler object, which can be used to invoke the instance by calling its Invoke member function.

void Terminate()#

For an instance handle, this indicates deleting an already created function instance.

The default timeout for the current kill request is 30 seconds. In scenarios such as high disk load or etcd failures, the kill request processing time may exceed 30 seconds, causing the interface to throw a timeout exception. Since the kill request has a retry mechanism, users can choose to ignore the timeout exception or retry after capturing it. For Range scheduling handles, this indicates deleting a group of already created function instances.

auto counter = YR::Instance(Counter::FactoryCreate).Invoke(1);
auto c = counter.Function(&Counter::Add).Invoke(1);
std::cout << "counter is " << *YR::Get(c) << std::endl;
counter.Terminate();

Throws:: Exception – An exception is thrown if the function instance deletion fails, along with corresponding error messages, such as deleting a function instance that has already exited prematurely or receiving a timeout when deleting the function instance response.

void Terminate(bool isSync)#

Supports synchronous or asynchronous termination.

For an instance handle, this indicates deleting an already created function instance. When synchronous termination is not enabled, the default timeout for the current kill request is 30 seconds. In scenarios such as high disk load or etcd failures, the kill request processing time may exceed 30 seconds, causing the interface to throw a timeout exception. Since the kill request has a retry mechanism, users can choose to ignore the timeout exception or retry after capturing it. When synchronous termination is enabled, this interface will block until the instance completely exits. For Range scheduling handles, this indicates deleting a group of already created function instances.

auto counter = YR::Instance(Counter::FactoryCreate).Invoke(1);
auto c = counter.Function(&Counter::Add).Invoke(1);
std::cout << "counter is " << *YR::Get(c) << std::endl;
counter.Terminate(true);

Parameters:: isSync – Whether to enable synchronous termination. If true, it sends a kill request with the signal killInstanceSync to the function-proxy, and the kernel synchronously kills the instance. If false, it sends a kill request with the signal killInstance to the function-proxy, and the kernel asynchronously kills the instance.
Throws:: Exception – An exception is thrown if the function instance deletion fails, along with corresponding error messages, such as deleting a function instance that has already exited prematurely or receiving a timeout when deleting the function instance response.

std::shared_future<void> AsyncTerminate(bool isSync)#

Supports synchronous or asynchronous termination.

For an instance handle, this indicates deleting an already created function instance. When synchronous termination is not enabled, the default timeout for the current kill request is 30 seconds. In scenarios such as high disk load or etcd failures, the kill request processing time may exceed 30 seconds, causing the interface to throw a timeout exception. Since the kill request has a retry mechanism, users can choose to ignore the timeout exception or retry after capturing it. When synchronous termination is enabled, this interface will block until the instance completely exits.

auto counter = YR::Instance(Counter::FactoryCreate).Invoke(1);
auto c = counter.Function(&Counter::Add).Invoke(1);
std::cout << "counter is " << *YR::Get(c) << std::endl;
counter.Terminate(true);

Parameters:: isSync – Whether to enable synchronous termination. If true, it sends a kill request with the signal killInstanceSync to the function-proxy, and the kernel synchronously kills the instance. If false, it sends a kill request with the signal killInstance to the function-proxy, and the kernel asynchronously kills the instance.
Returns:: A future for the kill result.

std::vector<NamedInstance<InstanceType>> GetInstances(int timeoutSec = NO_TIMEOUT)#

Specifies the timeout in seconds for waiting until a set of instances in Range scheduling are scheduled and their instance IDs are returned, generating a list of NamedInstance objects.

This parameter is optional. If provided, it uses the specified timeout; otherwise, it uses -1 to indicate an infinite wait.

int main(void)
{
    YR::Config conf;
    YR::Init(conf);

    YR::InstanceRange range;
    int rangeMax = 10;
    int rangeMin = 1;
    int rangeStep = 2;
    int rangeTimeout = 10;
    range.max = rangeMax;
    range.min = rangeMin;
    range.step = rangeStep;
    range.sameLifecycle = true;
    YR::RangeOptions rangeOpts;
    rangeOpts.timeout = rangeTimeout;
    range.rangeOpts = rangeOpts;
    YR::InvokeOptions opt;
    opt.instanceRange = range;
    auto instances = YR::Instance(Counter::FactoryCreate).Options(opt).Invoke(1);
    auto insList = instances.GetInstances(5);

    for (auto ins : insList) {
        auto res = ins.Function(&Counter::Add).Invoke(1);
        std::cout << "res is " << *YR::Get(res) << std::endl;
    }
    instances.Terminate();
    YR::Finalize();

    return 0;
}

Throws:: Exception – An exception is thrown if the backend interface call fails, such as due to insufficient resources, where multiple instances within the range are not scheduled, leading to a timeout when obtaining the instance ID list.
Returns:: A list of NamedInstance objects, which can be iterated to obtain the handles of individual instances for invocation.

FormattedMap Export() const#

Users can use this method to obtain handle information, which can be serialized and stored in databases or other persistent tools.

auto counter = YR::Instance(Counter::FactoryCreate).Invoke(100);
auto out = counter.Export();

Returns:: Handle information of NamedInstance stored in key-value pairs.

void Import(FormattedMap &input)#

Users can use this method to import handle information, which can be retrieved from databases or other persistent tools and deserialized for import.

NamedInstance<Counter> counter;
counter.Import(in);

Parameters:: input – Handle information of NamedInstance stored in key-value pairs.

NamedInstance

Contents

NamedInstance#