Group

Group#

class Group#

A class for managing the lifecycle of grouped instances.

The Group class is responsible for managing the lifecycle of grouped instances, including their creation and destruction. It follows the fate-sharing principle, where all instances in the group are created or destroyed together.

The Group class provides methods to create, terminate, and manage grouped instances. It ensures that all instances in the group are treated as a single unit, and any failure during group creation will roll back the entire group.

Public Functions

Group() = default#

Default constructor.

Group(std::string &name, GroupOptions &opts)#

Constructor.

Parameters:

  • name – Instance Group Scheduling Class Name, the name must be unique.

  • opts – See the structure GroupOptions.

Group(std::string &name, GroupOptions &&opts)#

Constructor.

Parameters:

  • name – Instance Group Scheduling Class Name, the name must be unique.

  • opts – See the structure GroupOptions.

void Invoke()#

Execute the creation of a group of instances following the fate-sharing principle.

This function is used to create a group of instances that share the same fate. All instances in the group will be created together, and if one instance fails, the entire group will be rolled back. The group configuration and options are defined in the GroupOptions. 

int main(void) {
  YR::Config conf;
  YR::Init(conf);
  std::string groupName = "";
  YR::InvokeOptions opts;
  opts.groupName = groupName;
  YR::GroupOptions groupOpts;
  groupOpts.timeout = 60;
  auto g = YR::Group(groupName, groupOpts);
  auto ins1 = YR::Instance(SimpleCaculator::Constructor).Options(opts).Invoke();
  auto ins2 = YR::Instance(SimpleCaculator::Constructor).Options(opts).Invoke();
  g.Invoke();
  return 0;
}

Note

Constraints

  • A single group can create a maximum of 256 instances.

  • Concurrent creation supports a maximum of 12 groups, with each group creating up to 256 instances.

  • Calling this interface after NamedInstance::Export() will cause the current thread to hang.

  • If this interface is not called, directly invoking stateful function requests and retrieving results will cause the current thread to hang.

  • Repeated calls to this interface will result in an exception being thrown.

  • Instances in the group do not support specifying a detached lifecycle.

Throws:

std::runtime_error – If an error occurs during group creation or if the interface is misused.

Returns:

void.

void Terminate()#

Terminate a group of instances.

This function is used to delete or terminate a group of instances that were created together. All instances in the group will be cleaned up or removed as a single unit, following the fate-sharing principle.

int main(void) {
    YR::Config conf;
    YR::Init(conf);
    std::string groupName = "";
    YR::InvokeOptions opts;
    opts.groupName = groupName;
    YR::GroupOptions groupOpts;
    auto g = YR::Group(groupName, groupOpts);
    auto ins1 = YR::Instance(SimpleCaculator::Constructor).Options(opts).Invoke();
    auto ins2 = YR::Instance(SimpleCaculator::Constructor).Options(opts).Invoke();
    g.Invoke();
    g.Terminate();
    return 0;
}

Note

Constraints

  • This function can only be called on a group that has been successfully created and invoked.

  • Calling this function multiple times on the same group will result in an exception being thrown.

  • If the group does not exist or has already been terminated, an exception will be thrown.

  • Termination will release all resources associated with the group and its instances.

Throws:

std::runtime_error – If the group does not exist, has already been terminated, or an error occurs during termination.

Returns:

void.

void Wait()#

Waits for the completion of grouped instance creation and execution.

This function blocks the current process until all instances in the group have completed their creation and execution. If the Invoke method has not been called before Wait, an exception is thrown.

int main(void) {
    YR::Config conf;
    YR::Init(conf);
    std::string groupName = "";
    YR::InvokeOptions opts;
    opts.groupName = groupName;
    YR::GroupOptions groupOpts;
    auto g = YR::Group(groupName, groupOpts);
    auto ins1 = YR::Instance(SimpleCaculator::Constructor).Options(opts).Invoke();
    auto ins2 = YR::Instance(SimpleCaculator::Constructor).Options(opts).Invoke();
    g.Invoke();
    g.Wait();  // Wait for all instances in the group to complete
    return 0;
}
Throws:

Exception – Thrown if the Invoke method has not been called before Wait or if the wait operation times out. The timeout duration is specified in the GroupOptions structure.

Returns:

void.

std::string GetGroupName() const#

Get the name of the group.

Returns:

The name of the group.

The parameter structure is supplemented with the following explanation:

struct GroupOptions#

Configuration options for grouped instance scheduling.

The GroupOptions structure defines parameters for the lifecycle management of grouped instances, including timeout settings for rescheduling when kernel resources are insufficient.

Public Members

int timeout = NO_TIMEOUT#

Timeout for rescheduling when kernel resources are insufficient, in seconds.

  • If set to -1, the kernel will retry scheduling indefinitely.

  • If set to a value less than 0, an exception will be thrown.

bool sameLifecycle = true#

Whether to enable the fate-sharing configuration for grouped instances.

  • true (default): Instances in the group will be created and destroyed together.

  • false: Instances can have independent lifecycles.

std::string strategy = "None"#

The strategy to create the group, default strategy is None.

  • 'None': No strategy.

  • 'PACK': Pack multiple instances into the same node as much as possible.

  • 'SPREAD': Distribute multiple instances across different nodes as much as possible.

  • 'STRICT_PACK': All instances must be placed on the same node, otherwise creation fails.

  • 'STRICT_SPREAD': All instances must be placed on different nodes, otherwise creation fails.

BindOptions bind#

Resource binding options.

Used to specify resource-level binding strategy.

struct BindOptions#

Configuration for resource binding affinity.

Public Members

std::string resource = "NONE"#

Resource type to bind to. default type is None.

  • 'None': No binding.

  • 'NUMA': Bind to NUMA nodes.

std::string strategy = "NONE"#

Binding strategy for the specified resource, default strategy is None.

  • 'None': Equivalent to Spread.

  • 'PACK': Pack multiple instances into the same resource units as much as possible.

  • 'SPREAD': Distribute multiple instances across different resource units as much as possible.