Skip to content

C++ Event Subscriptions API

Note

This is correct for only versions of sc-machine that >= 0.10.0.

The C++ Event Subscriptions API focuses on managing subscriptions to various events within the system. This documentation explains how agents can subscribe to specific events and receive notifications when these events occur. It is essential for building systems that require real-time updates and interactions based on event occurrences.

Note

To include this API provide #include <sc-memory/sc_event_subscription.hpp> in your hpp source.

ScEventSubscription

ScElementaryEventSubscription is base class for all sc-event subscription, it can be used to catch all sc-events for specified sc-element.

Each sc-event subscription constructor, besides ScElementaryEventSubscription constructor, takes 3 parameters:

  • context is an object of ScMemoryContext that will be used to work with sc-event;
  • subscriptionElementAddr is an object of ScAddr of sc-element that need to be listened for a specified sc-event;
  • delegateFunc is a delegate to a callback function, that will be called on each event emit (void delegateFunc(TScEvent const &)), where TScEvent is corresponding sc-event class.

Note

Callback function will be called in another thread!

Warning

Subscription sc-element must be valid sc-element.

Constructor of ScElementaryEventSubscription class takes 4 parameters:

  • context is an object of ScMemoryContext that will be used to work with sc-event;
  • eventClassAddr is an object of ScAddr of sc-event class;
  • subscriptionElementAddr is an object of ScAddr of sc-element that need to be listened for a specified sc-event;
  • delegateFunc is a delegate to a callback function, that will be called on each event emit (void delegateFunc(ScElementaryEvent const &)).

All these constructors are private, you can't call these. We provide more safe API to generate subscription. Use C++ Agent Context API to generate sc-event subscriptions.

All sc-event classes are in core keynodes:

  • ScKeynodes::sc_event_after_generate_connector;
  • ScKeynodes::sc_event_after_generate_outgoing_arc;
  • ScKeynodes::sc_event_after_generate_incoming_arc;
  • ScKeynodes::sc_event_after_generate_edge;
  • ScKeynodes::sc_event_before_erase_connector;
  • ScKeynodes::sc_event_before_erase_outgoing_arc;
  • ScKeynodes::sc_event_before_erase_incoming_arc;
  • ScKeynodes::sc_event_before_erase_edge;
  • ScKeynodes::sc_event_before_erase_element;
  • ScKeynodes::sc_event_before_change_link_content.

Use them as eventClassAddr for CreateElementaryEventSubscription.

The table of description (parameters of callback function named on pictures, if there are no parameter name on picture, then it's would have an empty value):

Note

Here context is pointer to object of ScAgentContext class.

Class Description
ScElementaryEventSubscription Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription(
  eventClassAddr,
  subscriptionElementAddr, 
  [](ScElementaryEvent const & event) -> void
{
  // Handle sc-event.
});
...
ScEventAfterGenerateConnector Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventAfterGenerateConnector>(
  subscriptionElementAddr, 
  [](ScEventAfterGenerateConnector const & event) -> void
{
  // Handle sc-event.
});
...
ScEventAfterGenerateOutgoingArc Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventAfterGenerateOutgoingArc>(
  subscriptionElementAddr, 
  [](ScEventAfterGenerateOutgoingArc const & event) -> void
{
  // Handle sc-event.
});
...
ScEventAfterGenerateIncomingArc Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventAfterGenerateIncomingArc>(
  subscriptionElementAddr, 
  [](ScEventAfterGenerateIncomingArc const & event) -> void
{
  // Handle sc-event.
});
...
ScEventAfterGenerateEdge Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventAfterGenerateEdge>(
  subscriptionElementAddr, 
  [](ScEventAfterGenerateEdge const & event) -> void
{
  // Handle sc-event.
});
...
ScEventBeforeEraseConnector Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventBeforeEraseConnector>(
  subscriptionElementAddr, 
  [](ScEventBeforeEraseConnector const & event) -> void
{
  // Handle sc-event.
});
...
ScEventBeforeEraseOutgoingArc Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventBeforeEraseOutgoingArc>(
  subscriptionElementAddr, 
  [](ScEventBeforeEraseOutgoingArc const & event) -> void
{
  // Handle sc-event.
});
...
ScEventBeforeEraseIncomingArc Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventBeforeEraseIncomingArc>(
  subscriptionElementAddr, 
  [](ScEventBeforeEraseIncomingArc const & event) -> void
{
  // Handle sc-event.
});
...
ScEventBeforeEraseEdge Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventBeforeEraseEdge>(
  subscriptionElementAddr, 
  [](ScEventBeforeEraseEdge const & event) -> void
{
  // Handle sc-event.
});
...
ScEventBeforeEraseElement Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventBeforeEraseElement>(
  subscriptionElementAddr, 
  [](ScEventBeforeEraseElement const & event) -> void
{
  // Handle sc-event.
});
...
ScEventBeforeChangeLinkContent Example C++ code: 

...
auto subscription = context->CreateElementaryEventSubscription<
  ScEventBeforeChangeLinkContent>(
  subscriptionElementAddr, 
  [](ScEventBeforeChangeLinkContent const & event) -> void
{
  // Handle sc-event.
});
...

Frequently Asked Questions

Whether a function is considered an agent if this function is subscribed to a sc-event and which is called after that sc-event occurs?

No, such functions are not agents. Agents have a strict specification. See C++ Agents API.

Why can't I call the constructor of a subscription class to sc-event?

First of all, it's not safe. We need more checks on input arguments because there are more of them. Secondly, it is correct from the OOP point of view. Constructors should not throw exceptions. Third, it is correct from the point of view of the architecture we use in the sc-machine. The ScAgentContext is a facade over all possible objects used by agents.

Are ScEventAfterGenerateIncomingArc or ScEventAfterGenerateOutgoingArc events trigger when ScEventAfterGenerateEdge event is triggered?

No, the ScEventAfterGenerateEdge event only occurs when sc-edges are generated.