High-level API

Overview

A high-level API is provided to generate messages in the batprotocol. This API is composed of the following.

• A main MessageBuilder class that manages a list of events and their serialization.

• Many helper classes to store temporary data for complex events.

For now the API is only available in C++. One can also use the JSON representation of each event. The JSON representation also provides a good view of the attributes consituting each event.

Todo

The documentation of the protocol API is a work in progress. Below are several examples of how to use each protocol event.

Feel free to contact us if anything is missing or you did not find the information you were looking for.

Message management API

C++JSON

Please refer to Getting started for now.

Todo

Document MessageBuilder message management functions with doxygen and include them here.

Job and profile management events

Execute job

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;
using namespace std;

// Execute a job by just stating on which hosts it should be allocated.
// Default placement policy will be done.
void execute_job_simple(MessageBuilder & builder)
{
    builder.add_execute_job("w0!0", "0-1");
}

// ExecuteJobOptions enables you to customize how the execution should be done.
// Here, a predefined placement strategy is used explicitly.
void execute_job_predefined_placement(MessageBuilder & builder)
{
    // This is the default predefined placement strategy.
    // It will put executor0 on host0, executor1 on host1... and so on.
    // If all hosts are filled this way, executorN will be put on host0, executorN+1 on host1...
    builder.add_execute_job("w0!1", "0-4", ExecuteJobOptions()
        .set_predefined_placement_strategy(fb::PredefinedExecutorPlacementStrategy_SpreadOverHostsFirst)
    );

    // This is another predefined placement strategy.
    // Here, the cores of each host will be filled before traversing all the hosts.
    // executor0 will be on host0, executor1 on host0... until all cores of host0 are filled.
    // Then it will do the same on other hosts, traversing them in order (host1, then host2...).
    builder.add_execute_job("w0!2", "0-4", ExecuteJobOptions()
        .set_predefined_placement_strategy(fb::PredefinedExecutorPlacementStrategy_FillOneHostCoresFirst)
    );
}

// Predefined placement strategies are convenient but do not fit all cases.
// You can use a custom executor to host mapping to create any fancy placement.
void execute_job_custom_placement(MessageBuilder & builder)
{
    // Here, we want to reserve two hosts but only use the first allocated one.
    // As we allocate hosts 13 and 17, this means only host 13 will be used.
    //
    // The number of required resources by the job is important to generate a custom placement.
    // Here, let us assume the job requires 4 resources.
    // Every one of the associated SimGrid executors must be placed.
    shared_ptr<vector<uint32_t> > placement(new vector<uint32_t>({0,0,0,0}));
    builder.add_execute_job("w0!3", "13 17", ExecuteJobOptions()
        .set_custom_placement(placement)
    );

    // Now, in this second example, we want to use the two allocated hosts.
    // The job is still assumed to required 4 resources, so we will place 4 executors.
    // Executor0 and 3 will be on the first allocated host (37).
    // Executor1 and 2 will be on the second allocated host (51).
    placement.reset(new vector<uint32_t>({0,1,1,0}));
    builder.add_execute_job("w0!4", "37 51", ExecuteJobOptions()
        .set_custom_placement(placement)
    );
}

// If the profiles of your job use abstract storage names,
// you can decide which storage to use when executing the job.
void execute_job_storage_mapping(MessageBuilder & builder)
{
    // Let us assume the profile uses a "pfs" abstract storage name.
    // You can decide at runtime that for this job, host 19 should be used as "pfs".
    builder.add_execute_job("w0!5", "0-3 19", ExecuteJobOptions()
        .override_storage_placement("pfs", 19)
    );

    // You can define the placement of several abstract storages if needed.
    builder.add_execute_job("w0!6", "0-3 13 21", ExecuteJobOptions()
        .override_storage_placement("burst_buffer", 13)
        .override_storage_placement("pfs", 19)
    );
}

// If your job uses a composed profiles (which means it has sub-profiles),
// you can define a specific host allocation or executor placement for some sub-profiles.
void execute_job_subprofile_placement(MessageBuilder & builder)
{
    // Let us assume your main profile is a sequential composition profile named "seq",
    // which uses two parallel tasks "ptask0" and "ptask1" as subprofiles.
    //
    // You can decide to let ptask0 use the job host allocation and executor placement,
    // but override it for ptask1 so that it only uses host0.
    shared_ptr<vector<uint32_t> > placement(new vector<uint32_t>({0,0,0,0}));
    builder.add_execute_job("w0!7", "0-3", ExecuteJobOptions()
        .override_profile_alloc_custom_placement("w0!ptask1", "0-3", placement)
    );

    // If you use the same profile several times in your composed profiles,
    // you can give a custom placement for specific ones with the advanced
    // profile syntax "workload!profile!instance".
    // For example, let us assume a "seq2" profile uses "ptask1" then "ptask1".
    // You can override the placement of these two instances separately, so that
    // the first ptask1 will only be on host13,
    // while the second ptask1 will only be on host21.
    //
    // For complex compositions (trees), instances of the same profiles are
    // numbered using an in-order walk starting at 0.
    builder.add_execute_job("w0!8", "13 21", ExecuteJobOptions()
        .override_profile_alloc_custom_placement("w0!ptask1!0", "13", placement)
        .override_profile_alloc_custom_placement("w0!ptask1!1", "21", placement)
    );

    // You can also use a different predefined strategy for some sub-profiles.
    builder.add_execute_job("w0!9", "13 21", ExecuteJobOptions()
        .override_profile_alloc_predefined_placement("w0!ptask1!0", "13 21", fb::PredefinedExecutorPlacementStrategy_FillOneHostCoresFirst)
    );
}

Reject job

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Reject a job instead of executing it.
void example_reject_job_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_reject_job("w0!0");
}

Kill jobs

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Kill a single job.
void example_kill_jobs_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_kill_jobs({"w0!0"});
}

// Kill several jobs in one decision.
// Kill acknowledgment will only be sent once all the involved jobs are killed.
void example_kill_jobs_multiple(batprotocol::MessageBuilder & builder)
{
    builder.add_kill_jobs({"w0!3", "w0!7", "dyn!0"});
}

Register job

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// Register a job dynamically.
void example_register_job_simple(batprotocol::MessageBuilder & builder)
{
    auto job = Job::make();
    job->set_resource_number(8);
    job->set_walltime(600.0);
    job->set_profile("w0!prof");

    builder.add_register_job("dyn!0", job);
}

// Register a job dynamically without walltime.
void example_register_job_no_walltime(batprotocol::MessageBuilder & builder)
{
    auto job = Job::make();
    job->set_resource_number(4);
    job->set_profile("w0!prof");

    builder.add_register_job("dyn!1", job);
}

Register profile

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <memory>
#include <vector>

#include <batprotocol.hpp>

using namespace batprotocol;

// Register a delay profile.
void example_register_profile_delay(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_delay(10.0);
    builder.add_register_profile("dyn!delay0", profile);
}

// Register a delay profile with extra_data.
void example_register_profile_delay_extra_data(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_delay(10.0);
    profile->set_extra_data("user-specified profile data");
    builder.add_register_profile("dyn!delay0-with-extra-data", profile);
}

// Register a parallel task profile.
void example_register_profile_ptask(batprotocol::MessageBuilder & builder)
{
    auto compute = std::vector<double>({1e7, 1e7, 1e7, 1e7});
    auto comm = std::vector<double>({
           0, 8192, 8192,    0,
        8192,    0,    0, 8192,
        8192,    0,    0, 8192,
           0, 8192, 8192,    0
    });
    auto profile = Profile::make_parallel_task(
        std::make_shared<std::vector<double> >(std::move(compute)),
        std::make_shared<std::vector<double> >(std::move(comm))
    );

    builder.add_register_profile("dyn!ptask0", profile);
}

// Register a parallel task profile (no communication).
void example_register_profile_ptask_no_comm(batprotocol::MessageBuilder & builder)
{
    auto compute = std::vector<double>({1e7, 1e7, 1e7, 1e7});
    auto profile = Profile::make_parallel_task(
        std::make_shared<std::vector<double> >(std::move(compute)),
        nullptr
    );

    builder.add_register_profile("dyn!ptask1", profile);
}

// Register a parallel task profile (no computation).
void example_register_profile_ptask_no_comp(batprotocol::MessageBuilder & builder)
{
    auto comm = std::vector<double>({
           0, 8192, 8192,    0,
        8192,    0,    0, 8192,
        8192,    0,    0, 8192,
           0, 8192, 8192,    0
    });
    auto profile = Profile::make_parallel_task(
        nullptr,
        std::make_shared<std::vector<double> >(std::move(comm))
    );

    builder.add_register_profile("dyn!ptask2", profile);
}

// Register a parallel task profile (no computation nor communication).
void example_register_profile_ptask_empty(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_parallel_task(
        nullptr,
        nullptr
    );

    builder.add_register_profile("dyn!ptask3", profile);
}

// Register an homogeneous parallel task profile.
void example_register_profile_ptask_hg(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_parallel_task_homogeneous(
        fb::HomogeneousParallelTaskGenerationStrategy_DefinedAmountsUsedForEachValue,
        1e7,
        8192
    );

    builder.add_register_profile("dyn!ptask_hg0", profile);
}

// Register an homogeneous parallel task (with a total amount given) profile.
void example_register_profile_ptask_hg_total(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_parallel_task_homogeneous(
        fb::HomogeneousParallelTaskGenerationStrategy_DefinedAmountsSpreadUniformly,
        1e7,
        8192
    );

    builder.add_register_profile("dyn!ptask_hg1", profile);
}

void example_register_profile_ptask_hg_storage(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_parallel_task_on_storage_homogeneous(
        "pfs",
        fb::HomogeneousParallelTaskGenerationStrategy_DefinedAmountsUsedForEachValue,
        0.0,
        4e6
    );

    builder.add_register_profile("dyn!ptask_hg_storage0", profile);
}

void example_register_profile_ptask_hg_storage_total(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_parallel_task_on_storage_homogeneous(
        "pfs",
        fb::HomogeneousParallelTaskGenerationStrategy_DefinedAmountsSpreadUniformly,
        1e9,
        0.0
    );

    builder.add_register_profile("dyn!ptask_hg_storage1", profile);
}

void example_register_profile_ptask_staging_between_storages(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_parallel_task_data_staging_between_storages(
        1e6,
        "pfs",
        "burst_buffer"
    );

    builder.add_register_profile("dyn!ptask_staging_storages0", profile);
}

void example_register_profile_trace_replay_smpi(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_trace_replay_smpi(
        "npb-lu/traces-smpi.txt"
    );

    builder.add_register_profile("dyn!replay_smpi0", profile);
}

void example_register_profile_trace_replay_fractional_comp(batprotocol::MessageBuilder & builder)
{
    auto profile = Profile::make_trace_replay_fractional_computation(
        "npb-lu/traces-fractional-comp.txt"
    );

    builder.add_register_profile("dyn!replay_frac_comp0", profile);
}

void example_register_profile_sequential(batprotocol::MessageBuilder & builder)
{
    auto sub_profiles = std::vector<std::string>({
        "w0!ptask",
        "dyn!ptask_hg0"
    });
    auto profile = Profile::make_sequential_composition(
        std::make_shared<std::vector<std::string> >(std::move(sub_profiles)),
        3
    );

    builder.add_register_profile("dyn!sequential0", profile);
}

void example_register_profile_forkjoin(batprotocol::MessageBuilder & builder)
{
    auto sub_profiles = std::vector<std::string>({
        "w0!ptask",
        "dyn!ptask_hg0"
    });
    auto profile = Profile::make_forkjoin_composition(
        std::make_shared<std::vector<std::string> >(std::move(sub_profiles))
    );

    builder.add_register_profile("dyn!forkjoin0", profile);
}

void example_register_profile_ptask_merge(batprotocol::MessageBuilder & builder)
{
    auto sub_profiles = std::vector<std::string>({
        "w0!ptask",
        "dyn!ptask_hg0"
    });
    auto profile = Profile::make_parallel_task_merge_composition(
        std::make_shared<std::vector<std::string> >(std::move(sub_profiles))
    );

    builder.add_register_profile("dyn!ptask_merge0", profile);
}

Job submitted

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// A simple job has been submitted.
void example_job_submitted_simple(batprotocol::MessageBuilder & builder)
{
    auto job = Job::make();
    job->set_resource_number(4);
    job->set_profile("w0!prof");
    job->set_walltime(3600.0);

    builder.add_job_submitted("w0!0", job, 0.0, "", nullptr);
}

// A job with extra data has been submitted.
void example_job_submitted_extra_data(batprotocol::MessageBuilder & builder)
{
    auto job = Job::make();
    job->set_resource_number(16);
    job->set_profile("w0!prof");
    job->set_extra_data(R"("application": "npb-lu")");

    builder.add_job_submitted("w0!1", job, 1.0, "", nullptr);
}

Job completed

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// A job finished successfully (not killed, returned 0)
void example_job_completed_success(batprotocol::MessageBuilder & builder)
{
    builder.add_job_completed("w0!0",
        fb::FinalJobState_COMPLETED_SUCCESSFULLY,
        0
    );
}

// A job finished with failure (not killed, returned non-0)
void example_job_completed_failure(batprotocol::MessageBuilder & builder)
{
    builder.add_job_completed("w0!1",
        fb::FinalJobState_COMPLETED_FAILED,
        1
    );
}

// A job finished by getting killed
void example_job_completed_killed(batprotocol::MessageBuilder & builder)
{
    builder.add_job_completed("w0!2",
        fb::FinalJobState_COMPLETED_KILLED,
        1
    );
}

Jobs killed

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// A single atomic profile got killed.
void example_jobs_killed_atomic_simple(MessageBuilder & builder)
{
    auto kill_progress = KillProgress::make("w0!prof!0");
    kill_progress->add_atomic("w0!prof!0", "w0!prof", 0.5);

    builder.add_jobs_killed({"w0!0"}, {{"w0!0", kill_progress}}, {});
}

// Two single atomic profiles got killed.
void example_jobs_killed_atomic_several_jobs(MessageBuilder & builder)
{
    auto kill_progress1 = KillProgress::make("w0!prof!3");
    kill_progress1->add_atomic("w0!prof!3", "w0!prof", 0.3);

    auto kill_progress2 = KillProgress::make("w0!prof!4");
    kill_progress2->add_atomic("w0!prof!4", "w0!prof", 0.7);

    builder.add_jobs_killed({"w0!3", "w0!4"}, {
            {"w0!3", kill_progress1},
            {"w0!4", kill_progress2}
        },
        {}
    );
}

// A sequential profile executing an atomic profil got killed.
void example_jobs_killed_sequential_simple(MessageBuilder & builder)
{
    auto kill_progress = KillProgress::make("w0!prof_seq!0");
    kill_progress->add_atomic("w0!prof!1", "w0!prof", 0.1);
    kill_progress->add_sequential("w0!prof_seq!0", "w0!prof_seq", 1, 2, "w0!prof!1");

    builder.add_jobs_killed({"w0!1"}, {{"w0!1", kill_progress}}, {});
}

// A sequential profile executing another sequential profile got killed.
void example_jobs_killed_sequential_recursive(MessageBuilder & builder)
{
    auto kill_progress = KillProgress::make("w0!prof_seq_seq!0");
    kill_progress->add_atomic("w0!prof!2", "w0!prof", 0.2);
    kill_progress->add_sequential("w0!prof_seq!1", "w0!prof_seq", 1, 2, "w0!prof!2");
    kill_progress->add_sequential("w0!prof_seq_seq!0", "w0!prof_seq_seq", 0, 0, "w0!prof_seq!1");

    builder.add_jobs_killed({"w0!2"}, {{"w0!2", kill_progress}}, {});
}

// A forkjoin profile executing atomic profiles got killed.
void example_jobs_killed_forkjoin_simple(MessageBuilder & builder)
{
    auto kill_progress = KillProgress::make("w0!prof_forkjoin!0");
    kill_progress->add_atomic("w0!prof!5", "w0!prof", 0.4);
    kill_progress->add_atomic("w0!prof2!0", "w0!prof2", 0.8);
    kill_progress->add_forkjoin("w0!prof_forkjoin!0", "w0!prof_forkjoin", {"w0!prof!5", "w0!prof2!0"});

    builder.add_jobs_killed({"w0!5"}, {{"w0!5", kill_progress}}, {});
}

// A forkjoin profile executing another forkjoin profile got killed.
void example_jobs_killed_forkjoin_recursive(MessageBuilder & builder)
{
    auto kill_progress = KillProgress::make("w0!prof_forkjoin2!0");
    kill_progress->add_atomic("w0!prof!6", "w0!prof", 0.9);
    kill_progress->add_forkjoin("w0!prof_forkjoin3!0", "w0!prof_forkjoin3", {"w0!prof!6"});
    kill_progress->add_forkjoin("w0!prof_forkjoin2!0", "w0!prof_forkjoin2", {"w0!prof_forkjoin3!0"});

    builder.add_jobs_killed({"w0!6"}, {{"w0!6", kill_progress}}, {});
}

Simulation management events

External Decision Component hello

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// An external decision component says hello!
void example_edc_hello_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_edc_hello("cpp-unit-test", "0.1.0", "unknown");
}

// External decision components that request various simulation features
void example_edc_hello_feature1(batprotocol::MessageBuilder & builder)
{
    builder.add_edc_hello("cpp-unit-test", "0.1.0", "unknown",
        EDCHelloOptions().request_dynamic_registration()
    );
}

void example_edc_hello_feature2(batprotocol::MessageBuilder & builder)
{
    builder.add_edc_hello("cpp-unit-test", "0.1.0", "unknown",
        EDCHelloOptions().request_dynamic_registration()
                         .request_profile_reuse()
    );
}

void example_edc_hello_feature3(batprotocol::MessageBuilder & builder)
{
    builder.add_edc_hello("cpp-unit-test", "0.1.0", "unknown",
        EDCHelloOptions().request_dynamic_registration()
                         .request_profile_reuse()
                         .request_acknowledge_dynamic_jobs()
    );
}

void example_edc_hello_feature4(batprotocol::MessageBuilder & builder)
{
    builder.add_edc_hello("cpp-unit-test", "0.1.0", "unknown",
        EDCHelloOptions().request_forward_profiles_on_job_submission()
    );
}

void example_edc_hello_feature5(batprotocol::MessageBuilder & builder)
{
    builder.add_edc_hello("cpp-unit-test", "0.1.0", "unknown",
        EDCHelloOptions().request_forward_profiles_on_jobs_killed()
    );
}

void example_edc_hello_feature6(batprotocol::MessageBuilder & builder)
{
    builder.add_edc_hello("cpp-unit-test", "0.1.0", "unknown",
        EDCHelloOptions().request_forward_profiles_on_simulation_begins()
    );
}

Simulation begins

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// A fully completed simulation begins.
void example_simulation_begins_full(batprotocol::MessageBuilder & builder)
{
    SimulationBegins begins;

    begins.set_batsim_info("5.0.0", "unknown");

    begins.add_host(0, "host0", 0, 1, fb::HostState_IDLE, 1,
        std::shared_ptr<std::vector<double> >(new std::vector<double>({1e9})));
    begins.add_host(1, "host1", 0, 2, fb::HostState_SLEEPING, 8,
        std::shared_ptr<std::vector<double> >(new std::vector<double>({1e9, 1e8})));
    begins.add_host(2, "pfs", 0, 1, fb::HostState_IDLE, 1,
        std::shared_ptr<std::vector<double> >(new std::vector<double>({1e9})));
    begins.set_host_number(3);

    begins.set_host_property(0, "a", "0");
    begins.set_host_property(0, "b", "1");
    begins.set_host_property(1, "a", "1");
    begins.set_host_property(1, "b", "3");

    begins.set_host_zone_property(0, "zone_key", "g5k");
    begins.set_host_zone_property(1, "zone_key", "g5k");

    begins.set_host_as_storage(2);

    begins.add_workload("w0", "/tmp/workload0.json");
    begins.add_workload("w1", "/tmp/workload1.json");

    begins.add_external_event_list("ee0", "/tmp/external_events0.txt");

    auto profile = Profile::make_delay(60.0);
    begins.add_profile("w0!delay0", profile);
    begins.add_profile("w1!delay0", profile);

    auto batsim_arguments = std::vector<std::string>({
        "batsim",
        "-p", "cluster_energy_128.xml",
        "-w", "test_energy_minimal_load0.json",
        "-e", "batres",
        "--energy"
    });
    begins.set_batsim_arguments(
        std::make_shared<std::vector<std::string> >(std::move(batsim_arguments))
    );

    begins.set_batsim_execution_context("another JSON string");

    builder.add_simulation_begins(begins);
}

Simulation ends

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// Simulation is about to end.
void example_simulation_ends_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_simulation_ends();
}

Simulation error

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Notifies an error in the simulation before terminating
void example_simulation_error(batprotocol::MessageBuilder & builder)
{
    builder.add_simulation_error("error in simulation");
}

Force simulation stop

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// The decision component forces to stop the simulation.
void example_force_simulation_stop_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_force_simulation_stop();
}

Call me later

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// Call me later, only once.
void example_call_me_later_one_shot(batprotocol::MessageBuilder & builder)
{
    auto when = TemporalTrigger::make_one_shot(42);
    builder.add_call_me_later("example_one_shot", when);
}

// Call me later, periodically (infinitely, every 10 seconds).
void example_call_me_later_periodic_10s(batprotocol::MessageBuilder & builder)
{
    auto when = TemporalTrigger::make_periodic(10);
    builder.add_call_me_later("example_infinite_period", when);
}

// Call me later, periodically (infinitely, every 500 milliseconds offset by 27 milliseconds).
void example_call_me_later_periodic_500ms(batprotocol::MessageBuilder & builder)
{
    auto when = TemporalTrigger::make_periodic(500);
    when->set_time_unit(batprotocol::fb::TimeUnit_Millisecond);
    when->set_offset(27);
    builder.add_call_me_later("example_infinite_period", when);
}

// Call me later, periodically (only 5 times).
void example_call_me_later_periodic_finite(batprotocol::MessageBuilder & builder)
{
    auto when = TemporalTrigger::make_periodic_finite(20, 5);
    builder.add_call_me_later("example_finite_period", when);
}

Stop call me later

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Stop a (non one shot) call me later.
void example_stop_call_me_later(batprotocol::MessageBuilder & builder)
{
    builder.add_stop_call_me_later("example_infinite_period");
}

Finish registration

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// The decision component stops registration of profiles/jobs.
void example_finish_registration_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_finish_registration();
}

Requested call

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// A requested call has been triggerred.
void example_requested_call_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_requested_call("example_one_shot", false);
}

// The last requested call from a non-infinite sequence has been triggerred.
void example_requested_call_finite_periodic_last(batprotocol::MessageBuilder & builder)
{
    builder.add_requested_call("example_finite_periodic_last", true);
}

External event occurred

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

void example_external_event_occurred_simple(batprotocol::MessageBuilder & builder)
{
    auto generic = ExternalEvent::make_generic_event("some generic data");

    builder.add_external_event_occurred("e0!0", generic);
}

All static jobs have been submitted

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// All static jobs have been submitted.
void example_all_static_jobs_submitted_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_all_static_jobs_have_been_submitted();
}

All static external events have been injected

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// All static external events have been injected.
void example_all_static_external_events_injected_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_all_static_external_events_have_been_injected();
}

Resource management events

Change hosts Pstate

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Change pstate of a few hosts represented as an Intervalset.
void example_change_hosts_pstate_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_change_hosts_pstate("1 4-12 23-24 165", 4);
}

Hosts Pstate changed

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// The pstate of some hosts has been changed.
void example_hosts_pstate_changed_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_hosts_pstate_changed("3 7-11 25-37 169", 7);
}

Turn on/off hosts

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Turn on/off hosts represented as an Intervalset.
void example_turn_onoff_hosts_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_turn_onoff_hosts("1 8-12 23-24 255", 1);
}

Hosts turned on/off

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// The state of some hosts has been changed.
void example_hosts_turned_onoff_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_hosts_turned_onoff("3 5 7-37 70", 3);
}

Probe management events

Create probe

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// Create a one shot probe.
void example_create_probe_one_shot(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_one_shot(30);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3");

    builder.add_create_probe("power-now", fb::Metrics_Power, create_probe);
}

// Create a periodic probe.
void example_create_probe_periodic(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_periodic(30);
    trigger->set_offset(5);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    auto links = std::vector<std::string>({
        "pfs",
        "pfs_UP",
        "pfs_DOWN"
    });
    create_probe->set_resources_as_links(
        std::make_shared<std::vector<std::string> >(std::move(links))
    );

    builder.add_create_probe("network-load-pfs", fb::Metrics_NetworkLoad, create_probe);
}

// Aggregate values over resources as a sum.
void example_create_probe_resource_aggregation_sum(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_one_shot(30);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .set_resource_aggregation_as_sum();

    builder.add_create_probe("power-now", fb::Metrics_Power, create_probe);
}

// Aggregate values over resources as an arithmetic mean.
void example_create_probe_resource_aggregation_arithmetic_mean(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_one_shot(30);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .set_resource_aggregation_as_arithmetic_mean();

    builder.add_create_probe("power-now", fb::Metrics_Power, create_probe);
}

// Aggregate values over resources as a median.
void example_create_probe_resource_aggregation_median(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_one_shot(30);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .set_resource_aggregation_as_median();

    builder.add_create_probe("power-now", fb::Metrics_Power, create_probe);
}

// Aggregate values over resources as a minimum.
void example_create_probe_resource_aggregation_min(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_one_shot(30);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .set_resource_aggregation_as_min();

    builder.add_create_probe("power-now", fb::Metrics_Power, create_probe);
}

// Aggregate values over resources as a maximum.
void example_create_probe_resource_aggregation_max(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_one_shot(30);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .set_resource_aggregation_as_max();

    builder.add_create_probe("power-now", fb::Metrics_Power, create_probe);
}

// Aggregate values over resources as a quantile function.
void example_create_probe_resource_aggregation_quantile_func(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_one_shot(30);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .set_resource_aggregation_as_quantile_function(0.25);

    builder.add_create_probe("power-now", fb::Metrics_Power, create_probe);
}

// Set an emission filtering threshold.
void example_create_probe_emission_filtering_threshold(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_periodic(30);
    trigger->set_offset(5);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .set_emission_filtering_as_threshold(1e6, fb::BooleanComparisonOperator_GreaterThanOrEqual);

    builder.add_create_probe("power", fb::Metrics_Power, create_probe);
}

// Accumulate values over time as a sum, resetting the value at every period.
void example_create_probe_accumulate_sum_reset(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_periodic(30);
    trigger->set_offset(5);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .enable_accumulation_with_reset(0.0, false, fb::CumulativeFunction_Sum);

    builder.add_create_probe("power", fb::Metrics_Power, create_probe);
}

// Accumulate values over time as a sum, without reset at every period.
void example_create_probe_accumulate_sum_no_reset(batprotocol::MessageBuilder & builder)
{
    auto trigger = TemporalTrigger::make_periodic(30);
    trigger->set_offset(5);
    auto create_probe = CreateProbe::make_temporal_triggerred(trigger);
    create_probe->set_resources_as_hosts("0-3")
                 .enable_accumulation_no_reset(true, fb::CumulativeFunction_Sum);

    builder.add_create_probe("power", fb::Metrics_Power, create_probe);
}

Stop probe

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Stop a persistent probe.
void example_stop_probe_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_stop_probe("power-all-hosts");
}

Reset probe

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Reset a cumulative (thus persistent) probe.
void example_reset_probe_simple(batprotocol::MessageBuilder & builder)
{
    builder.add_reset_probe("power-all-hosts", 1.0);
}

Trigger probe

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

// Trigger a persistent probe, forcing its data emission.
void example_trigger_probe_force(batprotocol::MessageBuilder & builder)
{
    builder.add_trigger_probe("power-all-hosts", true);
}

// Trigger a persistent probe, not forcing its data emission.
// This means the data will only be given back if data passes the probe's filtering policy.
void example_trigger_probe_no_force(batprotocol::MessageBuilder & builder)
{
    builder.add_trigger_probe("power-all-hosts", false);
}

Probe data emitted

C++JSON

// This is free and unencumbered software released into the public domain.
// For more information, please refer to <http://unlicense.org/>
#include <batprotocol.hpp>

using namespace batprotocol;

// Data from an aggregated probe is emitted.
void example_probe_data_emitted_aggregated(batprotocol::MessageBuilder & builder)
{
    auto probe_data = ProbeData::make_aggregated(1e6);
    probe_data->set_resources_as_hosts("0-3");

    builder.add_probe_data_emitted(
        "power-all-hosts",
        fb::Metrics_Power,
        probe_data,
        false,
        1,
        1
    );
}

// Data from a vectorial probe is emitted.
void example_probe_data_emitted_vectorial(batprotocol::MessageBuilder & builder)
{
    auto data = std::vector<double>({50, 30});
    auto probe_data = ProbeData::make_vectorial(
        std::make_shared<std::vector<double> >(std::move(data))
    );

    auto links = std::vector<std::string>({
        "switch0",
        "switch1"
    });
    probe_data->set_resources_as_links(
        std::make_shared<std::vector<std::string> >(std::move(links))
    );

    builder.add_probe_data_emitted(
        "power-switches",
        fb::Metrics_Power,
        probe_data,
        true,
        5,
        7
    );
}