Client Cache
NCache Client Cache is a synchronized local L1 cache that keeps cached data close to the application. By serving applicable operations locally, Client Cache reduces network trips to the clustered cache (L2 Cache) and improves application performance. The Client Cache configuration is maintained with the clustered cache rather than individually on client machines. When an application connects to the clustered cache, NCache provides the associated Client Cache configuration to the client. If Client Cache is enabled, the configured Client Cache becomes available to the client and is used for applicable cache operations.
A clustered cache can have one Client Cache configuration. The Client Cache name is automatically derived from the clustered cache name. For example, the Client Cache associated with defaultCache is named defaultCache_cc. NCache supports two Client Cache types: Regular and Full-Data. Both types can operate in InProc or OutProc isolation mode.
Regular Client Cache
A Regular Client Cache maintains a subset of the clustered cache data that is frequently accessed by the application. When the application requests an item that is not available locally, the item is retrieved from the clustered cache and populated in the Client Cache. Subsequent requests for the item can then be served locally. To ensure data integrity, the Client Cache synchronizes changes with the clustered cache (L2 Cache) through data change notifications and polling.
Because a Regular Client Cache contains only a subset of the clustered cache data, operations that require a complete dataset, such as SQL queries and GetByTags, are performed on the clustered cache.
All key-based write operations, such as Add, Insert, and Remove, are first performed on the clustered cache. Upon successful completion, the corresponding Client Cache data is populated or updated as required. For read operations, if the requested data is not available in the Client Cache, it is fetched from the clustered cache and populated locally.
Full-Data Client Cache
A Full-Data Client Cache maintains complete datasets for configured reference data types. When the Client Cache (L1 Cache) starts, it loads data belonging to those reference data types from the clustered cache (L2 Cache) and maintains the datasets locally. Reference data types allow applications to keep only the required datasets in the Client Cache instead of maintaining all data from the clustered cache.
Note
A Full-Data Client Cache requires more memory than a Regular Client Cache because it maintains complete datasets for its configured reference data types.
For configured reference data types, queries can be executed directly against the Client Cache when the required dataset is fully loaded, and will fall back to the clustered cache only if the data is partially loaded. Queries for non-configured data types are performed against the clustered cache.
By default, when requested data is unavailable locally or a configured dataset is only partially loaded, NCache can fall back to the clustered cache. Full-Data Client Cache also provides Strict Local Reads and Strict Query Enforcement through the configuration options provided in the NCache Management Center for applications that require operations to rely exclusively on locally available reference data.
For configured reference data types, key-based write operations such as Add, Insert, and Remove are first performed on the clustered cache. The corresponding changes are then synchronized with Client Cache instances through the background data synchronization mechanism described later.
Important
You cannot create a Full-Data Client Cache without configuring at least one reference data type.
Strict Local Reads
By default, key-based read operations first check the Client Cache (L1 Cache). If the requested item is not available locally, the operation falls back to the clustered cache. Strict Local Reads disables this fallback for configured reference data types. When enabled, a key that is not available in the Full-Data Client Cache (L1 Cache) results in a cache miss without retrieving the item from the clustered cache (L2 Cache). This behavior is useful when the application requires reads for configured reference data types to be served exclusively from locally available data. You can enable this by selecting "Return a cache miss for any key not found in the client cache, with no fallback to the clustered cache" checkbox through the NCache Management Center.
Strict Query Enforcement
Queries for configured reference data types are executed against the Full-Data Client Cache when the required dataset is completely loaded. If the dataset is only partially loaded, NCache falls back to the clustered cache. However, if you do not want queries to execute on the clustered cache, you can enable the Strict Query Enforcement feature. With this setting enabled, queries will execute only if the full dataset is present in the Client Cache. If the data is partially loaded, the query will fail immediately and throw the exception, "Unable to execute query on client cache as the type '{queryFQN}' is partially loaded." You can enable this by selecting the checkbox "Throw an exception when querying a partially loaded dataset in the client cache, with no fallback to the clustered cache" through the NCache Management Center.
Important
Strict Local Reads and Strict Query Enforcement apply only to reference data types configured for the Full-Data Client Cache.
Additionally, if a user attempts to execute a query on the Full-Data Client Cache while it is in a syncing state, such as during cache loading or resyncing, the operation will fail. In this case, NCache will throw the following exception: "Unable to execute query on client cache. Client Cache is still in syncing state."
Client Cache Configuration Model
The Client Cache configuration belongs to the clustered cache and is maintained on the cache server. Client applications do not require a separate Client Cache configuration to be maintained locally. When a client application connects, it receives the applicable Client Cache configuration and uses the Client Cache according to its configured isolation mode. This allows Client Cache behavior to be centrally configured while the actual L1 cache remains close to the application.
Client Cache can also be enabled or disabled without removing its configuration. Disabling Client Cache stops its use on connected clients while retaining the configuration. Applications remain connected to the clustered cache and continue performing cache operations directly against it. When Client Cache is enabled again, connected applications that previously initialized the Client Cache can resume using it without reconnecting. Applications that connected before Client Cache was configured must restart to initialize it.
Removing Client Cache is different from disabling it. Removal deletes the Client Cache configuration associated with the clustered cache.
Client Cache Isolation Modes
The isolation mode determines where the Client Cache instance runs relative to the application. NCache supports InProc and OutProc Client Caches.
The isolation mode is selected when the Client Cache is configured. To use a different isolation mode, remove the existing Client Cache configuration and create a new one with the required mode.
InProc Isolation Mode (In-Process)
An InProc Client Cache runs inside the application process, eliminating inter-process communication. User data is kept in object form to avoid deserialization cost, providing maximum performance for local cache access. Each application process hosts its own Client Cache instance. Therefore, Client Cache data is not shared between separate application processes, and each instance maintains its own copy of locally cached data. The lifetime of the Client Cache is also tied to the lifetime of the application process.
InProc mode is suitable when:
The application's hot dataset is not too large.
The application has only a few instances on each client machine with sufficient physical memory, since each application process maintains its own copy of Client Cache data.
The application lifecycle is long enough to benefit from the Client Cache. When the application process terminates, its InProc Client Cache and locally maintained data are also lost.
An InProc Client Cache can also be used by applications that reference NCache through NuGet packages without requiring an NCache Client installation on the client machine.
OutProc Isolation Mode
An OutProc Client Cache runs in a separate host process on the client machine. Applications communicate with the Client Cache outside their own process, allowing multiple application instances on the same machine to share a Client Cache instance. Although InProc outperforms OutProc mode in performance, OutProc mode comes with its own set of advantages.
Multiple applications running on the same client machine communicate with the same Client Cache. Multiple applications share data. Data loaded or updated by one application becomes available for other applications.
Application restart does not result in Client Cache data loss.
Fewer physical resources like RAM and CPU are required to run the Client Cache in OutProc mode as compared to InProc mode when each application process holds its copy of the Client Cache.
Synchronization of Client Cache data with clustered cache puts less burden on the clustered cache since you run a single Client Cache instance per client machine.
Note
An OutProc Client Cache requires NCache Client to be installed on the client machine.
OutProc Client Cache Failure and Recovery
If an OutProc Client Cache becomes unavailable, client requests are directed to the clustered cache (L2 Cache), allowing the application to continue performing cache operations without using the local Client Cache (L1 Cache). NCache automatically attempts to restore the Client Cache in the background.
If the OutProc Client Cache process crashes while the application is running, the client first performs its configured connection retries. After these retries are exhausted, the client retrieves the latest Client Cache configuration from the clustered cache and requests the NCache Service to start the Client Cache process. Once the Client Cache becomes available, the application resumes using it for applicable cache operations.
Synchronizing Data with Clustered Cache
Given that Client Cache holds a copy of clustered cache data, changes made to the data in the clustered cache must be propagated to the corresponding Client Cache instances. Multiple InProc or OutProc Client Cache instances can exist for the same clustered cache. NCache uses a background synchronization mechanism to keep these instances consistent with the clustered cache.
Regular Client Cache Synchronization
A Regular Client Cache does not perform initial data loading when it starts. It is populated when the application requests data that is not already available locally, causing that data to be fetched from the clustered cache.
When data is added to the Regular Client Cache, NCache tracks the locally cached keys so that changes made to the corresponding data in the clustered cache can be propagated to the affected Client Cache instances. Regular Client Cache synchronization is key-based; only data for keys already present in the Client Cache is synchronized.
Full-Data Client Cache Synchronization
When a Full-Data Client Cache starts, it performs an initial loading process. It loads data associated with its configured reference data types from the clustered cache to establish its local datasets.
Full-Data synchronization is based on configured reference data types. Changes to the corresponding data in the clustered cache are propagated to the Client Cache so that these datasets remain synchronized.
If eviction removes data belonging to a configured reference data type, the Full-Data Client Cache can reload that data when sufficient free capacity becomes available. The Data Reload Threshold specifies the percentage of the total Client Cache capacity that must be free before NCache attempts to reload the evicted reference data. The default value is 20%.
Reference data types are evicted and subsequently resynchronized or reloaded according to their configured priority. If a Full-Data Client Cache restarts, it reloads data for its configured reference data types from the clustered cache. If the clustered cache restarts, the Full-Data Client Cache clears its locally maintained data to preserve data integrity and resynchronizes with the clustered cache.
Change Notifications and Polling
NCache uses data change notifications together with polling to keep Client Cache instances synchronized with the clustered cache.
When data is added to the Client Cache, it registers a data change notification with the clustered cache for that data.
The clustered cache keeps track of the
CacheIteminstances held by Client Caches and monitors changes made to the corresponding data.When data is updated or removed from the clustered cache, the clustered cache records these changes.
A dedicated background worker thread inspects data changes every second, determines which Client Caches contain the affected keys, and sends data change notifications to those Client Caches.
A background worker thread on the Client Cache processes these notifications and requests the corresponding data updates from the clustered cache.
Client Cache also polls for data changes at the configured polling interval. The default polling interval is 10 seconds and acts as a fallback if a data change notification is missed.
This notification and polling mechanism allows Client Cache instances to synchronize locally cached data with changes made in the clustered cache.
Client Cache Synchronization Mode
Client Cache uses Optimistic Synchronization. When the requested data is available in the Client Cache, it is returned directly to the application while synchronization with the clustered cache occurs in the background.
This approach prioritizes local access while using the Client Cache synchronization mechanism to keep locally maintained data consistent with the clustered cache.
Client Cache Logging
Client Cache logging is managed together with client logging as part of the server-side client configuration. When client logging is enabled, logging is also enabled for the associated Client Cache. Client Cache logging does not require a separate logging configuration on the client machine.
Client logging is enabled by default. Any supported changes to client logging are centrally managed on the server and are provided to clients as part of their client configuration.
See Also
Cache Topologies
Dynamic Cluster
Local Cache
Cache Client
Bridge for Multi-site Replication
