GridGain Developers Hub
GitHub logo GridGain iso GridGain.com
GridGain Software Documentation

Peer Class Loading

Overview

Peer class loading refers to loading classes from a local node where they are defined to remote nodes. With peer class loading enabled, you don’t have to manually deploy your Java code on each node in the cluster and re-deploy it each time it changes — GridGain will automatically load the classes from the node where they are defined to the nodes where they are required.

For example, when querying data with a custom transformer, you only need to define your tasks on the client node that initiates the computation, and GridGain will load the classes to the server nodes.

When enabled, peer class loading is used to deploy the following classes:

This is what happens when a class is required on remote nodes:

  • GridGain will check if the class is available in the local classpath, i.e. if it was loaded at system initialization, and if it was, it will be returned. No class loading from a peer node will take place in this case.

  • If the class is not available locally, then a request for the class definition will be sent to the originating node. The originating node will send the class’s byte-code and the class will be loaded on the worker node. This happens once per class. When the class definition is loaded on a node, it will never have to be loaded again.

Enabling Peer Class Loading

Here is how peer class loading can be configured:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">

    <!-- Enable peer class loading. -->
    <property name="peerClassLoadingEnabled" value="true"/>

    <!-- Set deployment mode. -->
    <property name="deploymentMode" value="CONTINUOUS"/>

</bean>
IgniteConfiguration cfg = new IgniteConfiguration();

cfg.setPeerClassLoadingEnabled(true);

// Start a node.
Ignite ignite = Ignition.start(cfg);
var cfg = new IgniteConfiguration
{
    PeerAssemblyLoadingMode = PeerAssemblyLoadingMode.CurrentAppDomain
};
var ignite = Ignition.Start(cfg);

The following table describes parameters related to peer class loading.

Parameter Description Default value

PeerClassLoadingEnabled

Enables/disables peer class loading.

false

deploymentMode

The peer class loading mode.

SHARED

peerClassLoadingExecutorService

Configures a thread pool to be used for peer class loading. If not configured, a default pool is used.

null

peerClassLoadingExecutorServiceShutdown

Peer class loading executor service shutdown flag. If the flag is set to true, the peer class loading thread pool will be forcibly shut down when the node stops.

true

peerClassLoadingLocalClassPathExclude

List of packages in the system class path that should be P2P loaded even if they exist locally.

null

peerClassLoadingMissedResourcesCacheSize

Size of missed resources cache. Set to 0 to avoid caching of missing resources.

100

 

Peer Class Loading Modes

PRIVATE and ISOLATED

Classes deployed within the same class loader on the master node will still share the same class loader remotely on worker nodes. However, tasks deployed from different master nodes will not share the same class loader on worker nodes. This is useful in development environments when different developers can be working on different versions of the same classes. There is no difference between PRIVATE and ISOLATED deployment modes since the @UserResource annotation has been removed. Both constants were kept for backward-compatibility reasons and one of them is likely to be removed in a future major release.

In this mode, classes get un-deployed when the master node leaves the cluster.

SHARED

This is the default deployment mode. In this mode, classes from different master nodes with the same user version will share the same class loader on worker nodes. Classes will be un-deployed whenever all master nodes leave the grid or user version changes. This mode allows classes coming from different master nodes to share the same instances of user resources on remote nodes (see below). This method is specifically useful in production as, in comparison to ISOLATED mode which has a scope of a single class loader on a single master node, SHARED mode broadens the deployment scope to all master nodes.

In this mode, classes get un-deployed when all the master nodes leave the cluster.

CONTINUOUS

In CONTINUOUS mode, the classes do not get un-deployed when master nodes leave the cluster. Un-deployment only happens when a class user version changes. The advantage of this approach is that it allows tasks coming from different master nodes to share the same instances of user resources on worker nodes. This allows the tasks executing on worker nodes to reuse, for example, the same instances of connection pools or caches. When using this mode, you can start up multiple stand-alone worker nodes, define user resources on the master nodes, and have them initialized once on worker nodes regardless of which master node they came from. In comparison to the ISOLATED deployment mode which has a scope of a single class loader on a single master node, CONTINUOUS mode broadens the deployment scope to all master nodes which is specifically useful in production.

In this mode, classes do not get un-deployed even if all the master nodes leave the cluster.

Un-Deployment and User Versions

The classes deployed with peer class loading have their own lifecycle. On certain events (when the master node leaves or the user version changes, depending on deployment mode), the class information is un-deployed from the cluster: the class definition is erased from all nodes and the user resources linked with that class definition are also optionally erased (again, depending on deployment mode).

User version comes into play whenever you want to redeploy classes deployed in SHARED or CONTINUOUS modes. By default, GridGain will automatically detect if the class loader has changed or a node is restarted. However, if you would like to change and redeploy the code on a subset of nodes, or in the case of CONTINUOUS mode, kill every living deployment, you should change the user version. User version is specified in the META-INF/ignite.xml file of your class path as follows:

<!-- User version. -->
<bean id="userVersion" class="java.lang.String">
    <constructor-arg value="0"/>
</bean>

By default, all GridGain startup scripts (ignite.sh or ignite.bat) pick up the user version from the IGNITE_HOME/config/userversion folder. Usually, you just need to update the user version under that folder. However, in case of GAR or JAR deployment, you should remember to provide the META-INF/ignite.xml file with the desired user version in it.