API lifetime

The primary functionalities of ItalaApi are accessed through a core abstraction called the system, which acts as the root of the API. To begin using the library, user application must first create the system.

Warning

The user application is responsible for the system instance’s lifetime. Users must create the system before using any API functions and properly destroy it when it is no longer needed. ItalaApi can only be used as long as the system instance is alive.

Since the system is the root of the API, it is unique and only one instance can be created at a time.

The following examples demonstrate the basic lifecycle of creating, using, and disposing of the system instance in each supported language.

C++

The Itala::CreateSystem() function initializes the API and returns a pointer to the ISystem interface. The Dispose() method of this interface destroys the system instance.

#include <ItalaApi/Itala.h>

int main()
{
  // Create the system instance
  Itala::ISystem* pSystem = Itala::CreateSystem();

  // Use the ISystem interface...

  // Destroy the system instance
  pSystem->Dispose();
  pSystem = nullptr; // Good practice to avoid dangling pointers

  return 0;
}

C

The SYS_Initialize() function initializes the API. When finished, the SYS_Dispose() function must be called to release all resources.

#include "ItalaApiC/ItalaC.h"
#include <stdio.h>

int main()
{
  // Initialize the system
  ItalaError error = SYS_Initialize();
  if (error != ItalaErrorSuccess) {
    printf("Error initializing system!\n");
    return -1;
  }

  // Use ItalaApiC functions...

  // Dispose of the system
  error = SYS_Dispose();
  if (error != ItalaErrorSuccess) {
    printf("Error disposing system!\n");
  }

  return 0;
}

.NET

The static SystemFactory.Create() method initializes the API and returns an object implementing the ISystem interface. The Dispose() method should be called to clean up resources, which is often handled conveniently with a using block.

using Itala;

public static void Main(string[] args)
{
  // Create the system instance within a 'using' block for automatic disposal
  using (ISystem system = SystemFactory.Create())
  {
    // Use the ISystem interface...
  }
  // system.Dispose() is called automatically at the end of the block
}

.NET Framework

The static SystemFactory.Create() method initializes the API and returns an object implementing the ISystem interface. The Dispose() method should be called to clean up resources, which is often handled conveniently with a using statement.

using Itala;

public static void Main(string[] args)
{
  // Create the system instance
  ISystem system = SystemFactory.Create();

  // Use the ISystem interface...

  // Dispose of the system instance
  system.Dispose();
}

Python

The itala.create_system() function initializes the API and returns an ISystem object. The dispose() method on this object destroys the system instance. Using a with statement is the recommended pythonic way to ensure disposal.

from itala import itala

# Use a 'with' statement for automatic resource management
with itala.create_system() as system:
  # Use the ISystem interface...
  pass
# system.dispose() is called automatically upon exiting the 'with' block