Skip to content

5. Client API

Jump to bottom
Eneko Gonzalez edited this page Feb 25, 2025 · 5 revisions

5.1 Definitions

  • Event: Event is the smallest data unit in ChronoLog. All data pieces are stored as Events.
  • Story: Story is the structure organizing Events together with the ordering guarantee across them.
  • Chronicle: Chronicle is the structure collecting Stories together for easier data management.

5.2 Client class

The class used to manage the metadata interaction with ChronoLog through the ChronoLog Client Library

Client::Client(ChronoLog::ConfigurationManager const &confManager)
  • The constructor requires an object of ConfigurationManager to initialize the client object
int Client::Connect()
  • Connect to a ChronoLog deployment
  • Return CL_SUCCESS on success, error code otherwise
int Client::Disconnect()
  • Disconnect from a ChronoLog deployment
  • Return CL_SUCCESS on success, error code otherwise
int Client::CreateChronicle(std::string const &chronicle_name, std::map <std::string, std::string> const &attrs, int &flags)
  • Create a Chronicle named chronicle_name
  • Return CL_SUCCESS on success, error code otherwise
  • attrs is used to fine tune the property of the Chronicle such as the tiering policy
  • flags is used to enable or disable configuration flags during the creation
  • If there is no existing Chronicle with the same name, Chronicle chronicle_name will be created. Otherwise, an error code CL_ERR_CHRONICLE_EXISTS will be returned
int Client::DestroyChronicle(std::string const &chronicle_name)
  • Destroy the Chronicle named chronicle_name
  • Return CL_SUCCESS on success, error code otherwise
  • If the Chronicle has no Story being acquired, it will be destroyed. Otherwise, an error code CL_ERR_ACQUIRED will be returned
std::pair <int, StoryHandle*> Client::AcquireStory(std::string const &chronicle_name, std::string const &story_name, const std::map <std::string, std::string> &attrs, int &flags)
  • Acquire the Story with the name story_name under the Chronicle named chronicle_name to get ready for data access
  • A pair<int, StoryHandle *> will be returned on success. The first variable is the return value which should be CL_SUCCESS on success. The second one is a pointer to a StoryHandle object which manages access to the acquired Story.
  • If the Chronicle or the Story does not exist, an error code CL_ERR_NOT_EXIST will be returned
int Client::ReleaseStory(std::string const &chronicle_name, std::string const &story_name)
  • Release the Story with the name story_name under the Chronicle named chronicle_name
  • Return CL_SUCCESS on success, error code otherwise
int Client::DestroyStory(std::string const &chronicle_name, std::string const &story_name)
  • Destroy the Story with the name of story_name under the Chronicle named chronicle_name
  • Return CL_SUCCESS on success, error code otherwise
  • If the Story is being acquired, an error code CL_ERR_ACQUIRED will be returned

5.3 StoryHandle class

The class used to manage all Story-specific data access ChronoLog APIs such as recording.

int StoryHandle::log_event(std::string const &event_record)
  • Record Events to ChronoLog
  • Return CL_SUCCESS on success, error code otherwise
int StoryHandle::playback_story(uint64_t start, uint64_t end, std::vector<Event> &playback_events)
  • Retrieve all Events in the Story within the timestamp range [start, end].
  • The Events are stored in playback_events.
  • Returns CL_SUCCESS on success, an error code otherwise.
  • If start or end timestamps are out of range, an error code CL_ERR_OUT_OF_RANGE will be returned.

5.4 Event Class

The Event class represents the smallest data unit in ChronoLog. Each Event contains a timestamp, client ID, an index, and a log record.

Constructor

Event::Event(chrono_time event_time = 0, ClientId client_id = 0, chrono_index index = 0, std::string const &record = std::string())
  • Creates an Event object.
  • event_time: The timestamp of the event.
  • client_id: The client ID that generated the event.
  • index: The event index for ordering.
  • record: The actual data record of the event.

Getters

uint64_t Event::time() const
  • Returns the timestamp of the Event.
ClientId const &Event::client_id() const
  • Returns the client ID of the Event.
uint32_t Event::index() const
  • Returns the index of the Event.
std::string const &Event::log_record() const
  • Returns the log record of the Event.

Operators

bool Event::operator==(const Event &other) const
  • Checks if two Events are equal based on event_time, client_id, and eventIndex.
bool Event::operator!=(const Event &other) const
  • Checks if two Events are different.
bool Event::operator<(const Event &other) const
  • Compares Events based on event_time, then client_id, and finally eventIndex.
std::string Event::toString() const
  • Returns a string representation of the Event in the format: {Event:<eventTime>:<clientId>:<eventIndex>:<logRecord>}
Clone this wiki locally