Introduction to Coherence C++ Clients

7 Introduction to Coherence C++ Clients

Learn about Coherence for C++ and how to set up Coherence C++ application builds.

This chapter includes the following sections:

Overview of Coherence for C++
Coherence for C++ allows C++ applications to access Coherence clustered services, including data, data events, and data processing from outside the Coherence cluster.
Setting Up C++ Application Builds
Coherence C++ application builds require updating compiler settings, building header files, library linking, and setting environment variables.

Parent topic: Creating C++ Extend Clients

Overview of Coherence for C++

Coherence for C++ allows C++ applications to access Coherence clustered services, including data, data events, and data processing from outside the Coherence cluster. Typical uses of Coherence for C++ include desktop and web applications that require access to Coherence caches. See Installing the C++ Client Distribution in Installing Oracle Coherence.

Coherence for C++ consists of a native C++ library that connects to a Coherence*Extend clustered service instance running within the Coherence cluster using a high performance TCP/IP-based communication layer. This library sends all client requests to the Coherence*Extend clustered service which, in turn, responds to client requests by delegating to an actual Coherence clustered service (for example, a partitioned or replicated cache service).

A NamedCache instance is retrieved by using the CacheFactory::getCache(...) API call. After it is obtained, a client accesses the NamedCache in the same way as it would if it were part of the Coherence cluster. The fact that NamedCache operations are being sent to a remote cluster node (over TCP/IP) is completely transparent to the client application.

Note:

The C++ client follows the interface and concepts of the Java client, and users familiar with Coherence for Java should find migrating to Coherence for C++ straight forward.

Parent topic: Introduction to Coherence C++ Clients

Setting Up C++ Application Builds

Coherence C++ application builds require updating compiler settings, building header files, library linking, and setting environment variables.

This section includes the following topics:

Parent topic: Introduction to Coherence C++ Clients

Setting up the Compiler for Coherence-Based Applications

When integrating Coherence for C++ into your application's build process, it is important that certain compiler and linker settings be enabled. Some settings are optional, but still highly recommended.

*MSVC (Visual Studio)*

Table 7-1 Compiler Settings for MSVC (Visual Studio)

Setting	Build Type	Required?	Description
/EHsc	All	Yes	Enables C++ exception support
/GR	All	Yes	Enables C++ RTTI
/O2	Release	No	Enables speed optimizations
/MD	Release	Yes	Link against multi-threaded DLLs
/MDd	Debug	Yes	Link against multi-threaded debug DLLs

g++

Table 7-2 Compiler Settings for g++

Setting	Build Type	Required	Description
-O3	Release	No	Enables speed optimizations
-m32 / -m64	All	No	Explicitly set compiler to 32 or 64 bit mode

Parent topic: Setting Up C++ Application Builds

Including Coherence Header Files

Coherence ships with a set of header files that uses the Coherence API and must be compiled with your application. The header files are available under the installation's include directory. The include directory must be part of your compiler's include search path.

Parent topic: Setting Up C++ Application Builds

Linking the Coherence Library

Coherence for C++ ships with a release version of the Coherence library. This library is also suitable for linking with debug versions of application code. The library is located in the installation's lib directory. During linking, this directory must be part of your linkers library path.

Table 7-3 Names of Linking Libraries for Release and Debug Versions

Operating System	Library
Windows	coherence.lib
Linux	libcoherence.so
macOS	libcoherence.dylib

Parent topic: Setting Up C++ Application Builds

Setting the run-time Library and Search Path

During execution of a Coherence enabled application the Coherence for C++ shared library must be available from your application's library search path. This is achieved by adding the directory which contains the shared library to an operating system dependent environment variable. The installation includes libraries in its lib subdirectory.

Table 7-4 Name of the Coherence for C++ Library and Environment Variables

Operating System	Environment Variable
Windows	PATH
Linux	LD_LIBRARY_PATH
macOS	DYLD_LIBRARY_PATH

For example, to set the PATH environment variable on Windows execute:

c:\coherence\coherence-cpp\examples> set PATH=%PATH%;c:\coherence\coherence-cpp\lib

As with the Java version of Coherence, the C++ version supports a concept of System Properties to override configuration defaults. System Properties in C++ are set by using standard operating system environment variables, and use the same names as their Java counterparts. The coherence.cacheconfig system property specifies the location of the cache configuration file. You may also set the configuration location programmatically (CacheFactory::configure()) from application code, the examples however do not do this.

Table 7-5 Cache Configuration System Property Value for Various Operating Systems

Operating System	System Property
Windows	coherence.cacheconfig
Linux	CoherenceCacheConfig
macOS	CoherenceCacheConfig

Note:

Some operating system shells, such as the UNIX bash shell, do not support environment variables which include the '.' character. In this case, you may specify the name in camel case, where the first letter, and every letter following a '.' is capitalized. That is, "coherence.cacheconfig" becomes "CoherenceCacheConfig".

For example, to set the configuration location on Windows execute:

c:\coherence\coherence-cpp\examples> set coherence.cacheconfig=config\extend-cache-config.xml

Parent topic: Setting Up C++ Application Builds

Deploying Coherence for C++

Coherence for C++ requires no specialized deployment configuration. Simply link your application with the Coherence library. See the C++ examples included in the Coherence Examples for sample build scripts and configuration. The examples are included as part of the Coherence for Java distribution.

Parent topic: Setting Up C++ Application Builds