Apache Ignite.NET Documentation

The Apache Ignite .NET Developer Hub

Welcome to the Apache Ignite .NET developer hub. You'll find comprehensive guides and documentation to help you start working with Apache Ignite.NET as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Clients and Servers

Automatically distinguish between client and server nodes.

Overview

Ignite .NET has an optional notion of client and server nodes. Server nodes participate in caching, compute execution, stream processing, etc., while the native client nodes provide ability to connect to the servers remotely. Ignite native clients allow to use the whole set of Ignite APIs, including near caching, transactions, compute, streaming, services, etc. from the client side.

By default, all Ignite nodes are started as server nodes, and client mode needs to be explicitly enabled.

Another Ignite mode is Thin Client, which is very different from native client nodes. Thin clients are very lightweight and do not participate in cluster topology. Each thin client connects to a specific Ignite node through a socket and performs all operations through that node. Thin Client API is similar to full Ignite API, but has less features.

Configuring Clients and Servers

You can configure a node to be either a client or a server via IgniteConfiguration.clientMode property.

Alternatively, for convenience, you can also enable or disable the client mode on the Ignition class itself, to allow clients and servers reuse the same configuration.

Ignition.ClientMode = true;

// Start Ignite in client mode.
IIgnite ignite = Ignition.Start();

Creating Distributed Caches

Whenever creating caches in Ignite, either in XML or via any of the IIgnite.CreateCache(...) or IIgnite.GetOrCreateCache(...) methods, Ignite will automatically deploy the distributed cache on all server nodes.

Once a distributed cache is created, it will be automatically deployed on all the existing and future server nodes.

// Enable client mode locally.
Ignition.ClientMode = true;

// Start Ignite in client mode.
IIgnite ignite = Ignition.Start();

// Create cache on all the existing and future server nodes.
// Note that since the local node is a client, it will not 
// be caching any data.
var cache = ignite.GetOrCreateCache<object, object>("cacheName");

Computing on Clients or Servers

By default IgniteCompute will execute jobs on all the server nodes. However, you can choose to execute jobs only on server nodes or only on client nodes by creating a corresponding cluster group.

ICompute compute = ignite.GetCompute();

// Execute computation on the server nodes (default behavior).
compute.Broadcast(new MyComputeAction());
IClusterGroup clientGroup = ignite.GetCluster().ForClientNodes(null);

ICompute clientCompute = clientGroup.GetCompute();

// Execute computation on the client nodes.
clientCompute.Broadcast(new MyComputeAction());

Client Reconnect

Client nodes can get disconnected from the cluster in several cases:

  • When a client node cannot re-establish the connection with the server node due to network issues.
  • Connection with the server node was broken for some time; the client node is able to re-establish the connection with the server, but server already dropped the client node since the server did not receive client heartbeats
  • Slow clients can be kicked out by server nodes.

When a client determines that it is disconnected from the cluster, it assigns a new node 'id' to itself and tries to reconnect to the cluster. Note that this has side effect - the 'id' property of the local ClusterNode will change in case of client reconnection. This means that any application logic that relied on the 'id' value may be affected.

While a client is in a disconnected state and an attempt to reconnect is in progress, the Ignite API throws a special exception - IgniteClientDisconnectedException. This exception provides ClientReconnectTask property which returns a task that will be completed when the reconnection is finished (IgniteCache API throws CacheException which has IgniteClientDisconnectedException as InnerException). This task can also be obtained via IIgnite.ClientReconnectTask.

There are Ignite events for client reconnect (these events are local, i.e. they are fired only on client node): EventType.ClientNodeDisconnected and EventType.ClientNodeReconnected.

Also there are ClientDisconnected and ClientReconnected events in IIgnite.

var compute = ignite.GetCompute();

while (true) 
{
    try 
    {
        compute.Run(job);
    }
    catch (ClientDisconnectedException e) 
    {
        e.ClientReconnectTask.Wait(); // Wait for reconnection.

        // Can proceed and use the same ICompute instance.
    }
}
var cache = ignite.GetOrCreateCache("myCache");

while (true) 
{
  try 
  {
    cache.Put(key, val);
  }
  catch (CacheException e) 
  {
    var discEx = e.InnerException as ClientDisconnectedException;
    
    if (discEx != null) 
    {
      discEx.ClientReconnectTask.Wait();

      // Can proceed and use the same ICache instance.
    }
  }
}

Automatic client reconnection can be disabled using the 'ClientReconnectDisabled' property on TcpDiscoverySpi. When reconnection is disabled, client node is stopped.

var cfg = new IgniteConfiguration
{
    DiscoverySpi = new TcpDiscoverySpi
    {
        ClientReconnectDisabled = true
    }
};
<discoverySpi type="TcpDiscoverySpi" clientReconnectDisabled="true" />

Managing Slow Clients

In many deployments client nodes are launched outside of the main cluster on slower machines with worse network. In these scenarios it is possible that servers will generate load (such as continuous queries notification, for example) that clients will not be able to handle, resulting in growing queue of outbound messages on servers. This may eventually cause either out-of-memory situation on server or blocking the whole cluster if back-pressure control is enabled.

To manage these situations, you can configure the maximum number of allowed outgoing messages for client nodes. If the size of outbound queue exceeds this value, such a client node will be disconnected from the cluster preventing global slowdown.

Examples below show how to configure slow client queue limit in XML configuration.

var cfg = new IgniteConfiguration
{
    CommunicationSpi = new TcpCommunicationSpi
    {
        SlowClientQueueLimit = 1000
    }
};
<igniteConfiguration>
    <communicationSpi type="TcpCommunicationSpi" slowClientQueueLimit="1000" />
</igniteConfiguration>
<bean id="grid.cfg" class="org.apache.ignite.configuration.IgniteConfiguration">
  <property name="communicationSpi">
    <bean class="org.apache.ignite.spi.communication.tcp.TcpCommunicationSpi">
      <property name="slowClientQueueLimit" value="1000"/>
    </bean>
  </property>
</bean>

Clients and Servers


Automatically distinguish between client and server nodes.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.