http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/application-plugins.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/application-plugins.html.md.erb b/geode-docs/nativeclient/client-cache/application-plugins.html.md.erb new file mode 100644 index 0000000..8d23295 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/application-plugins.html.md.erb @@ -0,0 +1,262 @@ +--- +title: Specifying Application Plug-In Attributes +--- + +<a id="application-plugins__section_E81DB00AE0784BA2819DB3683C257647"></a> +The plug-in attributes allow you to customize client region behavior for loading, updating, deleting, and overflowing region data and for accessing data in server partitioned regions. All client plug-ins are available through the C++ and .NET API. + +Application plug-ins for cache regions in clients can be declared either programmatically or in the `cache.xml` file. + + +<a id="application-plugins__fig_630074710E134805A96B50AA5373866F"></a> +<span class="figtitleprefix">Figure: </span>Where Application Plug-Ins Run + +<img src="../common/images/client-cache-plugins-run.gif" alt="Where Application Plug-Ins Run" id="application-plugins__image_23F82DD7DCD543239F3A75F112282C46" class="image" /> + +## <a id="application-plugins__section_8FEB62EEC7A042E0A85E0FEDC9F71597" class="no-quick-link"></a>Overview of Application Plug-ins + +The API provides the framework for application plug-ins with callback functions for the appropriate events. Your classes and functions can customize these for your application's needs. When creating a region, specify these as part of the region's attributes settings. For regions already in the cache, you can specify new `CacheLoader`, `CacheWriter`, and `CacheListener` using the region's `AttributesMutator`. The `PartitionResolver` is not mutable. + +- `CacheLoader`: A data loader called when an entry get operation fails to find a value for a given key. A cache loader is generally used to retrieve data from an outside source such as a database, but it may perform any operation defined by the user. Loaders are invoked as part of the distributed loading activities for entry retrieval, described in [Entry Retrieval](accessing-entries.html#accessing-entries__section_AD6AFD842C144C128FA1C7F0B9283372). +- `CacheWriter`: A synchronous event listener that receives callbacks before region events occur and has the ability to abort the operations. Writers are generally used to keep a back-end data source synchronized with the cache. +- `CacheListener`: An asynchronous event listener for region events in the local cache. +- `PartitionResolver`: Used for single-hop access to partitioned region entries on the server side. This resolver implementation must match that of the `PartitionResolver` on the server side. + +The following XML declaration specifies a cache loader for a region when the region is created. + +``` pre +<region-attributes> + <cache-loader library-name="appl-lib" + library-function-name ="createCacheLoader"> + </cache-loader> +</region-attributes> +``` + +The rest of this section gives more detailed descriptions of these application plug-ins, followed by special considerations for plug-ins in distributed regions and some guidelines for writing callbacks. + +## <a id="application-plugins__section_FD3057C0416840BAB76850E115F48B5C" class="no-quick-link"></a>CacheLoader + +A cache loader is an application plug-in used to load data into the region. When an entry is requested that is unavailable in the region, a cache loader may be called upon to load it. Generally, you use a cache loader to retrieve the data from a database or another source outside the distributed system, but it may perform any operation defined by the user. + +The `CacheLoader` interface provides one function, `load`, for customizing region entry loading. A distributed region may have cache loaders defined in any or all caches where the region is defined. When loading an entry value, a locally defined cache loader is always used before a remote loader. In distributed regions, loaders are available for remote entry retrieval. + +## <a id="application-plugins__section_1754F575011742A59149FD280CEA0F16" class="no-quick-link"></a>CacheWriter + +A cache writer is an application plug-in that synchronously handles changes to a region's contents. It is generally used to keep back-end data sources synchronized with a cache region. A cache writer has callback functions to handle region destruction and entry creation, update, and destruction. These functions are all called before the modification has taken place and can abort the operation. + +You can also use cache writers to store data that you want to make persistent. + +## <a id="application-plugins__section_3F43B898CD254076B4DD777E9B4CC8F0" class="no-quick-link"></a>CacheListener + +A cache listener is an application plug-in that asynchronously handles changes to a region's contents. A cache listener has callback functions to handle region destruction and invalidation, along with entry creation, update, invalidation, and destruction. These functions are called asynchronously after the modification has taken place. + +This declarative XML example establishes a cache listener when a region is created: + +``` pre +<region name="region11"> + <region-attributes> + <cache-listener library-name="appl-lib" + library-function-name ="createCacheListener" /> + </region-attributes> +</region> +``` + +Unlike cache loaders and cache writers, cache listeners only receive events for entries to which the client has performed operations or registered interest. + +When the listener is attached to a region with caching disabled, the old value is always `NULL`. + +**Note:** +Do not perform region operations inside the cache listener. Once you have configured a cache listener, the event supplies the new entry values to the application. Performing a get with a key from the `EntryEvent` can result in distributed deadlock. For more about this, see the online API documentation for `EntryEvent`. + +When a region disconnects from a cache listener, you can implement the `afterRegionDisconnected` callback event. This callback event is only be invoked when using the `pool` API and `subscription` is enabled on the pool. For example: + +``` pre +class DisconnectCacheListener : public CacheListener +{ + void afterRegionDisconnected( const RegionPtr& region ) + { + printf("After Region Disconnected event received"); + } +}; +``` + +## <a id="application-plugins__section_348E00A84F274D4B9DBA9ECFEB2F012E" class="no-quick-link"></a>PartitionResolver + +This section pertains to data access in server regions that have custom partitioning. Custom partitioning uses a Java `PartitionResolver` to colocate like data in the same buckets. For the client, you can use a `PartitionResolver` that matches the server's implementation to access data in a single hop. With single-hop data access, the client pool maintains information on where a partitioned region's data is hosted. When accessing a single entry, the client directly contacts the server that hosts the key--in a single hop. + +**Note:** +Single hop is used for the following operations: `put`, `get`, `destroy`, `putAll`, `getAll`, `removeAll` and `onRegion` function execution. + +**Implementing Single-Hop on a Partitioned Region** + +1. Make sure the pool attribute, `pr-single-hop-enabled`, is set to `true` or not set. It is `true` by default. +2. If the server uses a custom `PartitionResolver` install an implementation of `PartitionResolver` in the client region that returns, entry for entry, the same value as the server's Java `PartitionResolver` implementation. The server uses the resolver to colocate like data within a partitioned region. + + If the server does not use a custom resolver, the default resolvers in client and server match, so single hop will work there by default. + +Disable single hop behavior for a region by setting its pool attribute `pr-single-hop-enabled` to `false`. + +See [<client-cache> Element Reference](../../reference/topics/client-cache.html) for information on setting `pr-single-hop-enabled`. + +See [Partitioned Regions](../../developing/partitioned_regions/chapter_overview.html) for more information, including colocating like data within a partitioned region and how to get the best performance with PR single hop. + +**Implementing a PartitionResolver** + +See [Custom-Partitioning and Colocating Data](../../developing/partitioned_regions/overview_custom_partitioning_and_data_colocation.html) for information on custom-partitioning the server partitioned regions. + +1. Implement `PartitionResolver` in the same place that you did in the server--custom class, key, or cache callback argument. +2. Program the resolver's functions the same way you programmed them in the Java implementation. Your implementation must match the server's. + + Example of programming the `PartitionResolver` in C++: + + ``` pre + class TradeKeyResolver : public PartitionResolver + { + private: + string m_tradeID; + int m_month; + int m_year; + public: + TradeKeyResolver() { } + TradeKeyResolver(int month, int year) { + m_month = month; + m_year = year; + } + + ~TradeKeyResolver() { } + + static PartitionResolverPtr createTradeKeyResolver() { + PartitionResolverPtr tradeKeyResolver( new TradeKeyResolver()); + return tradeKeyResolver; + } + const char* getName() { + return "TradeKey"; + } + CacheableKeyPtr getRoutingObject(const EntryEvent& opDetails) { + return CacheableKey::create(m_month + m_year); + } + }; + ``` + + Example of programming the `PartitionResolver` in C\#: + + ``` pre + using System; + using System.Threading; + // Use the GemFire namespace + using GemStone.GemFire.Cache; + class TradeKeyResolver : IPartitionResolver + { + private int m_month = 0; + private int m_year = 0; + + public static TradeKeyResolver CreateTradeKeyResolver() + { + return new TradeKeyResolver(); + } + + public virtual ICacheableKey GetRoutingObject(EntryEvent entry) + { + return new CacheableInt32(m_month + m_year); + } + + public virtual String GetName() + { + return "TradeKeyResolver"; + } + } + ``` + +3. Install the resolver in the region. Use one of these methods: + + XML partition resolver declaration: + + ``` pre + <region name="trades" refid="CACHING_PROXY"> + <region-attributes> + <partition-resolver library-name="appl-lib" library-function-name= + "createTradeKeyResolver"/> + </region-attributes> + </region> + <pool free-connection-timeout="12345" idle-timeout="5555" + load-conditioning-interval="23456" max-connections="7" + min-connections="3" name="test_pool_1" ping-interval="12345" + read-timeout="23456" retry-attempts="3" server-group="ServerGroup1" + socket-buffer-size="32768" statistic-interval="10123" + subscription-ack-interval="567" subscription-enabled="true" + subscription-message-tracking-timeout="900123" + subscription-redundancy="0" thread-local-connections="5" + pr-single-hop-enabled="true" > + <locator host="localhost" port="34756"/> + </pool> + ``` + + Programmatic partition resolver installation: + + ``` pre + void setPartitionResolver() + { + CachePtr cachePtr = CacheFactory::createCacheFactory()->create(); + PartitionResolverPtr resolver( new TradeKeyResolver()); + RegionFactoryPtr regionFactory = + cachePtr->createRegionFactory(PROXY) + ->setClientNotificationEnabled(true) + ->setPartitionResolver(resolver); + RegionPtr regionPtr = regionFactory->create( "Trades" ); + } + ``` + +Your implementation of `PartitionResolver` must match that of the server side. + +## <a id="application-plugins__section_4EC30A57C37E4DDF83990A264D2C0284" class="no-quick-link"></a>Using AttributesMutator to Modify a Plug-In + +A cache listener, cache loader or cache writer can be added to or removed from a region after the region is created by retrieving and running the `Region` object's `AttributesMutator`. Mutable attributes define operations that are run from the client itself. + +This example shows how to use `AttributesMutator` to dynamically add a cache listener to an existing region. + +``` pre +void setListener(RegionPtr& region) +{ + CacheListenerPtr regionListener = new TestCacheListener(); + AttributesMutatorPtr regionAttributesMutator = + region->getAttributesMutator(); + + // Change cache listener for region. + regionAttributesMutator->setCacheListener(regionListener); +} +``` + +The plug-ins can also be implemented using a dynamically linked library. The class is not available to the application code in this case, so a `factory` method is required by the `set` function along with the name of the library. + +This example shows how to use `AttributesMutator` along with the `setCacheListener` function to obtain a new cache listener object using the `factory` function provided by the library. Next, the listener is set for the region. + +``` pre +void setListenerUsingFactory(RegionPtr& region) +{ + AttributesMutatorPtr regionAttributesMutator = + region->getAttributesMutator(); + + // Change cache listener for region. + regionAttributesMutator->setCacheListener("Library", "createTestCacheListener"); +} +``` + +To use `AttributesMutator` to remove a plug-in from a region, set the plug-in's value to `NULLPTR`, as shown in the following example. + +``` pre +void removeListener(RegionPtr& region) +{ + CacheListenerPtr nullListener = NULLPTR; + AttributesMutatorPtr regionAttributesMutator = + region->getAttributesMutator(); + + // Change cache listener for region to NULLPTR + regionAttributesMutator->setCacheListener(nullListener); +} +``` + +## <a id="application-plugins__section_428DCC57B6344603AA19DCAFCE483A10" class="no-quick-link"></a>Considerations for Implementing Callbacks + +Keep your callback implementations lightweight and prevent situations that might cause them to hang. For example, do not perform distribution operations or disconnects inside events. + +Your code should handle any exceptions that it generates. If not, Geode handles them as well as possible. Because C++ has no standard for exceptions, in many cases Geode can only print an `unknown error` message.
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/cache-management.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/cache-management.html.md.erb b/geode-docs/nativeclient/client-cache/cache-management.html.md.erb new file mode 100644 index 0000000..1f9004d --- /dev/null +++ b/geode-docs/nativeclient/client-cache/cache-management.html.md.erb @@ -0,0 +1,29 @@ +--- +title: Cache Management +--- + +This section covers cache management. + +<a id="using-thread-safety__section_165DAD3CE6CA44D9A883FC91D4F09343"></a> + +- **[Client-to-Server Connection Process](../../nativeclient/client-cache/client-to-server-connection.html)** + + It is important to understand the sequence of events that occur when the native client connects with a Geode cache server. + +- **[Controlling Cache Size](../../nativeclient/client-cache/controlling-cache-size.html)** + + You can control cache size through region size limits, cache size limits, or a combination of the two. + +- **[Managing the Lifetime of a Cached Object](../../nativeclient/client-cache/managing-lifetime-cached-object.html)** + + All cacheable objects derive from `SharedBase` , which provides reference counting. Cacheable objects are referenced using `SharedPtr` types. + +- **[Using Thread Safety in Cache Management](../../nativeclient/client-cache/using-thread-safety.html)** + + When you perform structural changes on your cache, such as creating or closing a `Cache`, `Pool`, or `Region`, synchronize your operations or do them in a single thread. + +- **[Troubleshooting](../../nativeclient/client-cache/troubleshooting.html)** + + This section provides troubleshooting information for the native client. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/cache-ownership.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/cache-ownership.html.md.erb b/geode-docs/nativeclient/client-cache/cache-ownership.html.md.erb new file mode 100644 index 0000000..37f010c --- /dev/null +++ b/geode-docs/nativeclient/client-cache/cache-ownership.html.md.erb @@ -0,0 +1,11 @@ +--- +title: Local, Remote, and Distributed Caches +--- + +The *distributed system* defines how native client and cache server processes find each other. + +The distributed system keeps track of its membership list and makes its members aware of the identities of the other members in the distributed system. + +A cache for a native client is referred to as its *local cache*. All other caches in the distributed system are considered *remote caches* to the application. Every cache server and application process has its own cache. The term *distributed cache* is used to describe the union of all caches in a Geode distributed system. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/caches.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/caches.html.md.erb b/geode-docs/nativeclient/client-cache/caches.html.md.erb new file mode 100644 index 0000000..cfc456c --- /dev/null +++ b/geode-docs/nativeclient/client-cache/caches.html.md.erb @@ -0,0 +1,27 @@ +--- +title: Caches +--- + +The cache is the entry point to native client data caching in Geode. Through the cache, native clients gain access to the Geode caching framework for data loading, distribution, and maintenance. + +- **[About the Native Client Cache](../../nativeclient/client-cache/overview-client-cache.html)** + + The cache consists of data regions, each of which can contain any number of entries. Region entries hold the cached data. Every entry has a key that uniquely identifies it within the region and a value where the data object is stored. + +- **[Cache APIs](../../nativeclient/client-cache/caching-apis.html)** + + The native client has two cache APIs, `RegionService` and `Cache`. + +- **[Local, Remote, and Distributed Caches](../../nativeclient/client-cache/cache-ownership.html)** + + The *distributed system* defines how native client and cache server processes find each other. + +- **[Creating and Accessing a Cache](../../nativeclient/client-cache/create-access-cache.html)** + + When you create a native client cache, you are creating a native client cache instance. You must provide some basic configuration information such as a connection name and cache initialization parameters for the native client's cache instance. + +- **[Closing the Cache](../../nativeclient/client-cache/closing-cache.html)** + + Use the `Cache::close` function to release system resources when you finish using the cache. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/caching-apis.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/caching-apis.html.md.erb b/geode-docs/nativeclient/client-cache/caching-apis.html.md.erb new file mode 100644 index 0000000..455fbf0 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/caching-apis.html.md.erb @@ -0,0 +1,28 @@ +--- +title: Cache APIs +--- + +The native client has two cache APIs, `RegionService` and `Cache`. + +## <a id="caching-apis__section_8F81996678B64BBE94EF352527F7F006" class="no-quick-link"></a>RegionService API + +`RegionService` provides: + +- Access to existing cache regions. +- Access to the standard query service for the cache, which sends queries to the servers. See [Remote Querying](../remote-querying/remote-querying.html#security) and [Continuous Querying](../continuous-querying/continuous-querying.html#security). + +`RegionService` is inherited by `Cache`. + +You do not use instances of `RegionService` except for secure client applications with many users. See [Creating Multiple Secure User Connections with RegionService](../security/createsecureconnregionservice.html#security). + +## <a id="caching-apis__section_403383B9B5044A939A89A5BBB4915452" class="no-quick-link"></a>Cache API + +Use the `Cache` to manage your client caches. You have one `Cache` per client. + +The `Cache` inherits `RegionService` and adds management of these client caching features: + +- Region creation. +- Subscription keepalive management for durable clients. +- Access to the underlying distributed system. +- `RegionService` creation for secure access by multiple users. + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/caching-enabled.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/caching-enabled.html.md.erb b/geode-docs/nativeclient/client-cache/caching-enabled.html.md.erb new file mode 100644 index 0000000..1ce9960 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/caching-enabled.html.md.erb @@ -0,0 +1,27 @@ +--- +title: CachingEnabled +--- + +This attribute determines whether data is cached in this region. For example, you might choose to configure the distributed system as a simple messaging service where clients run without a cache. + +**Note:** +You can configure the most common of these options with the predefined region attributes. See [RegionShortcuts](region-shortcuts.html#region-shortcuts) and the Javadocs for `RegionShortcut`. + +If `CachingEnabled` is false (no caching), an `IllegalStateException` is thrown if any of these attributes are set: + +- [InitialCapacity](initial-capacity.html#initial-capacity) +- `EntryTimeToLive` under [Specifying Expiration Attributes](expiration-attributes.html#expiration-attributes) +- `EntryIdleTimeout` under [Specifying Expiration Attributes](expiration-attributes.html#expiration-attributes) +- [LoadFactor](load-factor.html#load-factor) +- [ConcurrencyLevel](concurrency-level.html#concurrency-level) +- [LruEntriesLimit](lru-entries-limit.html#concept_75D723D60E044FF9AE97C939699AB10A) +- [DiskPolicy](disk-policy.html#disk-policy) + +The following declaration enables caching for the region: + +``` pre +<region-attributes caching-enabled="true"> +</region-attributes> +``` + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/chapter-overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/chapter-overview.html.md.erb b/geode-docs/nativeclient/client-cache/chapter-overview.html.md.erb new file mode 100644 index 0000000..d898928 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/chapter-overview.html.md.erb @@ -0,0 +1,37 @@ +--- +title: Configuring the Native Client Cache +--- + +*Configuring the Native Client Cache* describes the native client cache functionality, initialization file, and APIs. It provides information about creating and working with caches, cache regions, and region entries. + +The native client cache provides a framework for native clients to store, manage, and distribute application data. + +- **[Caches](../../nativeclient/client-cache/caches.html)** + + The cache is the entry point to native client data caching in Geode. Through the cache, native clients gain access to the Geode caching framework for data loading, distribution, and maintenance. + +- **[Cache Initialization File (cache.xml)](../../nativeclient/cache-init-file/chapter-overview.html)** + + To ease the task of managing the structure of the cache, you can define the default Geode cache structure in an XML-based initialization file. + +- **[Regions](../../nativeclient/client-cache/regions.html)** + + You create cache regions either programmatically or through declarative statements in the `cache.xml` file. Generally, a cache is organized and populated through a combination of the two approaches. + +- **[Region Entries](../../nativeclient/client-cache/entries.html)** + + Region entries hold cached application data. Entries are automatically managed according to region attribute settings. + +- **[Region Consistency](../../nativeclient/client-cache/consistency_checking_in_regions.html)** + + Geode ensures that all copies of a region eventually reach a consistent state on all members and clients that host the region. + +- **[Region Attributes](../../nativeclient/client-cache/region-attributes.html)** + + Region attributes govern the automated management of a region and its entries. + +- **[Cache Management](../../nativeclient/client-cache/cache-management.html)** + + This section covers cache management. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/client-to-server-connection.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/client-to-server-connection.html.md.erb b/geode-docs/nativeclient/client-cache/client-to-server-connection.html.md.erb new file mode 100644 index 0000000..e2008a5 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/client-to-server-connection.html.md.erb @@ -0,0 +1,39 @@ +--- +title: Client-to-Server Connection Process +--- + +It is important to understand the sequence of events that occur when the native client connects with a Geode cache server. + +<a id="client-to-server-connection__section_C1E805D842FD44B984041C2ED1D4C2EF"></a> + +1. A native client region is configured in `cache.xml` or programmatically with a set of server connection endpoints. Server endpoints identify each cache server by specifying the server's name and port number. + + Client threads obtain, use, and release a connection to a connection pool that maintains new connections. The number of connections that a client can establish is governed by the pool's `min-connections` and `max-connections` settings, either using client XML configuration or programmatically through the `CacheFactory::setMinConnections()` and `CacheFactory::setMaxConnections()` APIs. The defaults for `min-connections` is 1 and `max-connections` is -1 meaning the connection count can grow to accommodate the number of active threads performing region operations. + + This example shows how to use `cache.xml` to configure a native client region with endpoints set to two cache servers: + + ``` pre + <pool name="examplePool" subscription-enabled="true" > + <server host="java_servername1" port="java_port1" /> + <server host="java_servername2" port="java_port2" /> + </pool> + <region name="NativeClientRegion" refid="CACHING_PROXY"> + <region-attributes pool-name="examplePool"/> + </region> + ``` + TCP connections on the native client are specified at the cache level, or by overriding endpoints for specific regions. The connections are created as the regions are created. In addition, connections can also get created for querying without having any created regions. In this case, when endpoints are defined at the cache level no regions are yet created and a query is fired. + + You can configure client-server connections in two ways. Use either the region/cache endpoints or the Pool API. For more information about the pool API, see [Using Connection Pools](../connection-pools/connection-pools.html#using-connection-pools). + +2. The client announces to the server which entries it wishes to have updated by programmatically registering interest in those entries. See [Registering Interest for Entries](registering-interest-for-entries.html#registering-interest-for-entries) for more information. + +3. The client `cache.xml` file should have the following parameters configured so the client can update the server and the client can receive updates from the server: + - Caching enabled in the client region, by using the `CACHING_PROXY RegionShortcut` setting in the region attribute `refid`. A listener could also be defined so event notification occurs. You can use both, but at least one of the two methods must be used by the client to receive event notifications. + - Set `subscription-enabled` to `true` so the client receives update notifications from the server for entries to which it has registered interest. + +4. A native client application calls the C++ or .NET API to connect to a cache server. +5. The client and the cache server exchange a handshake over a configured endpoint to create a connection. +6. Any `create`, `put`, `invalidate`, and `destroy` events sent to the server are propagated across the distributed cache so the client can receive the events. + +**Note:** +You may be able to improve system performance by making adjustments to the cache server. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/closing-cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/closing-cache.html.md.erb b/geode-docs/nativeclient/client-cache/closing-cache.html.md.erb new file mode 100644 index 0000000..fcd53e2 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/closing-cache.html.md.erb @@ -0,0 +1,11 @@ +--- +title: Closing the Cache +--- + +Use the `Cache::close` function to release system resources when you finish using the cache. + +After the cache is closed, any further method calls on the cache or any region object result in a `CacheClosedException` . + +If the cache is in a durable client, you need to use the `keepalive` version of the close method. See [Disconnecting From the Server](../preserving-data/disconnecting-from-server.html#concept_3A9AC62F96FA44DBBB5CCBFD3EA19B56). + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/concurrency-checks-enabled.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/concurrency-checks-enabled.html.md.erb b/geode-docs/nativeclient/client-cache/concurrency-checks-enabled.html.md.erb new file mode 100644 index 0000000..5c81fa6 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/concurrency-checks-enabled.html.md.erb @@ -0,0 +1,18 @@ +--- +title: ConcurrencyChecksEnabled +--- + +This attribute determines whether members perform checks to provide consistent handling for concurrent or out-of-order updates to distributed regions. + +A client cache can disable consistency checking for a region even if server caches enable consistency checking for the same region. This configuration ensures that the client sees all events for the region, but it does not prevent the client cache region from becoming out-of-sync with the server cache. + +Optionally enable concurrency checks for the region. Example: + +``` pre +<region-attributes concurrency-checks-enabled="true"> +</region-attributes> +``` + +See [Region Consistency](consistency_checking_in_regions.html#concept_77340A4999AC4861972A0EE10303E557) for more information. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/concurrency-level.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/concurrency-level.html.md.erb b/geode-docs/nativeclient/client-cache/concurrency-level.html.md.erb new file mode 100644 index 0000000..08e0582 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/concurrency-level.html.md.erb @@ -0,0 +1,18 @@ +--- +title: ConcurrencyLevel +--- + +<a id="concurrency-level__section_20FB0B9EEE9442BAAD87E3C488610866"></a> +This attribute estimates the maximum number of application threads that concurrently access a region entry at one time. This attribute helps optimize the use of system resources and reduce thread contention. + +The following declaration sets the region's `ConcurrencyLevel` to `16`: + +``` pre +<region-attributes concurrency-level="16"> +</region-attributes> +``` + +**Note:** +When `CachingEnabled` is `false`, do not set the `ConcurrencyLevel` attribute. An `IllegalStateException` is thrown if the attribute is set. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/consistency_checking_in_regions.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/consistency_checking_in_regions.html.md.erb b/geode-docs/nativeclient/client-cache/consistency_checking_in_regions.html.md.erb new file mode 100644 index 0000000..87c3303 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/consistency_checking_in_regions.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Region Consistency +--- + +Geode ensures that all copies of a region eventually reach a consistent state on all members and clients that host the region. + +By default Geode members perform consistency checks when they apply updates to a distributed region, in order to ensure that all copies of the region eventually become consistent on all Geode members and client caches that host the region. Different types of region ensure consistency using different techniques. However, when consistency checking is enabled (the default) all entries in a region require additional overhead in order to store version and timestamp information. + +Although a region must have the same consistency checking configuration on all Geode members that host the region, you can optionally disable consistency checking in a client cache region while leaving consistency checking enabled for the region on Geode members. This configuration may be necessary in certain cases where the client must view all updates to a given region, even when Geode members discards an update in order to preserve region consistency. + +See [Consistency for Region Updates](../../developing/distributed_regions/region_entry_versions.html#topic_CF2798D3E12647F182C2CEC4A46E2045) for more information. + +## <a id="concept_77340A4999AC4861972A0EE10303E557__section_167CD194A5374C64B4064783490F3EA8" class="no-quick-link"></a>Native Client Overhead for Consistency Checks + +In the native client regions, the overhead for performing consistency check is an additional 11 bytes per region entry. This overhead is slightly smaller than the overhead required to provide consistency checking on server-side region entries. + +If you cannot support the additional overhead in your deployment, you can disable consistency checks by setting the region attribute `concurrency-checks-enabled` to false for each region hosted by your client. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/controlling-cache-size.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/controlling-cache-size.html.md.erb b/geode-docs/nativeclient/client-cache/controlling-cache-size.html.md.erb new file mode 100644 index 0000000..e67b5ac --- /dev/null +++ b/geode-docs/nativeclient/client-cache/controlling-cache-size.html.md.erb @@ -0,0 +1,20 @@ +--- +title: Controlling Cache Size +--- + +You can control cache size through region size limits, cache size limits, or a combination of the two. + +<a id="controlling-cache-size__section_A0C25D6D1D5243778800AE67CAD8CB2C"></a> +Geode controls region size by moving least recently used (LRU) entries from the region or from all cache regions. + +## <a id="controlling-cache-size__section_3C7994A4C9D9468F860D99C0ED086D74" class="no-quick-link"></a>Controlling Region Size + +You can cap the size of any region with the region attribute [LruEntriesLimit](lru-entries-limit.html#concept_75D723D60E044FF9AE97C939699AB10A). You can specify whether to destroy the entries or overflow them to disk in the attribute [DiskPolicy](disk-policy.html#disk-policy). If you overflow entries to disk, you must also specify the attribute [PersistenceManager](persistence-manager.html#persistence-manager). + +## <a id="controlling-cache-size__section_E59CA4D5724147DC83E8991E654AC155" class="no-quick-link"></a>Controlling Cache Size + +You can control overall cache size with the [heap-lru-limit](../setting-properties/attributes-gfcpp.html#attributes-gfcpp), which is set in `gfcpp.properties`. This property sets the maximum amount of memory used for the cache, in megabytes. If a new entry causes memory to grow past this limit, the LRU algorithm is called to evict entries. Heap LRU causes eviction to occur on all regions in the cache, overriding region-level [LruEntriesLimit](lru-entries-limit.html#concept_75D723D60E044FF9AE97C939699AB10A) settings when it needs to reclaim memory. + +For each region, evictions are performed according to the region's `DiskPolicy` and `PersistenceManager` settings. If you use `heap-lru-limit`, review these region attributes for all your caching regions, to be sure you are evicting the way you want to. + +The related [heap-lru-delta](../setting-properties/attributes-gfcpp.html#attributes-gfcpp) property, also set in `gfcpp.properties`, is the amount of memory to free up once the LRU evictions have begun. Memory is reclaimed until the amount of memory used is below `heap-lru-limit` minus `heap-lru-delta`. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/create-access-cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/create-access-cache.html.md.erb b/geode-docs/nativeclient/client-cache/create-access-cache.html.md.erb new file mode 100644 index 0000000..b0fde6f --- /dev/null +++ b/geode-docs/nativeclient/client-cache/create-access-cache.html.md.erb @@ -0,0 +1,53 @@ +--- +title: Creating and Accessing a Cache +--- + +When you create a native client cache, you are creating a native client cache instance. You must provide some basic configuration information such as a connection name and cache initialization parameters for the native client's cache instance. + +When you create a cache, you provide the following input: + +- **Connection name**. Used in logging to identify both the distributed system connection and the cache instance. If you do not specify a connection name, a unique (but non-descriptive) default name is assigned. +- **`cache.xml` to initialize the cache (if the initialization is not done programmatically)**. To modify the cache structure, edit `cache.xml` in your preferred text editor. No changes to the application code are required. If you do not specify a cache initialization file, you need to initialize the cache programmatically. + +The `cache.xml` file contains XML declarations for cache, region, and region entry configuration. + +This XML declares server connection pools and regions: + +``` pre +<cache> + <region name="clientRegion1" refid="PROXY"> + <region-attributes pool-name="serverPool1"/> + </region> + <region name="clientRegion2" refid="PROXY"> + <region-attributes pool-name="serverPool2"/> + </region> + <region name="localRegion3" refid="LOCAL"/> + <pool name="serverPool1"> + <locator host="host1" port="40404"/> + </pool> + <pool name="serverPool2"> + <locator host="host2" port="40404"/> + </pool> +</cache> + +``` + +When you use the regions, the client regions connect to the servers through the pools named in their configurations. + +This file can have any name, but is generally referred to as `cache.xml` . + +For a list of the parameters in the `cache.xml` file, including the DTD, see [Cache Initialization File](../cache-init-file/chapter-overview.html#chapter-overview). + +To create your cache, call the `CacheFactory create` function. + +The `cache` object it returns gives access to the native client caching API. For example: + +``` pre +CacheFactoryPtr cacheFactory = CacheFactory::createCacheFactory(); +CachePtr cachePtr = cacheFactory->create(); + +``` + +**Note:** For more information on how to create a cache, see [Pivotal GemFire Native Client C++ API](../cpp-caching-api/cpp-caching-api.html#concept_CEC658A999414AC3A494578C214BF64E) or [Pivotal GemFire Native Client .NET API](../dotnet-caching-api/dotnet-caching-api.html#concept_FC6776DCE6ED48B887A6137761104AA4). + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/declarative-region-creation.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/declarative-region-creation.html.md.erb b/geode-docs/nativeclient/client-cache/declarative-region-creation.html.md.erb new file mode 100644 index 0000000..5c018c1 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/declarative-region-creation.html.md.erb @@ -0,0 +1,38 @@ +--- +title: Declarative Region Creation +--- + +Declarative region creation involves placing the region's XML declaration, with the appropriate attribute settings, in the `cache.xml` file that is loaded at cache creation. + +**Note:** +Before creating a region, specify region attributes. See [Region Attributes](region-attributes.html#region-attributes). + +Regions are placed inside the cache declaration in `region` elements. For example: + +``` pre +<cache> + <pool name="examplePool" subscription-enabled="true" > + <server host="localhost" port="40404" /> + </pool> + <region name="A" refid="PROXY"> + <region-attributes pool-name="examplePool"/> + </region> + <region name="A1"> + <region-attributes refid="PROXY" pool-name="examplePool"/> + </region> + <region name="A2" refid="CACHING_PROXY"> + <region-attributes pool-name="examplePool"> + <region-time-to-live> + <expiration-attributes timeout="120" action="invalidate"/> + </region-time-to-live> + </region-attributes> + </region> +</cache> + +``` + +The `cache.xml` file contents must conform to the DTD provided in the `productDir/dtd/gfcpp-cache8000.dtd` file. For details, see [Cache Initialization File](../cache-init-file/chapter-overview.html#chapter-overview). + +**Note:** For more information on how to create a region, see [Working with the C++ API](../cpp-caching-api/cpp-caching-api.html#concept_CEC658A999414AC3A494578C214BF64E), [Working with the .NET API](../dotnet-caching-api/dotnet-caching-api.html#concept_FC6776DCE6ED48B887A6137761104AA4), and the native client API reference. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/disk-policy.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/disk-policy.html.md.erb b/geode-docs/nativeclient/client-cache/disk-policy.html.md.erb new file mode 100644 index 0000000..d862004 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/disk-policy.html.md.erb @@ -0,0 +1,34 @@ +--- +title: DiskPolicy +--- + +<a id="disk-policy__section_F3A921FC67B44DD795BD9B5C180FCBB1"></a> +If the `lru-entries-limit` attribute is greater than zero, the optional `disk-policy` attribute determines how over-limit LRU entries are handled. LRU entries over the limit are either destroyed by default (`disk-policy` is none ) or written to disk (`overflows`). + +**Note:** +If `LruEntriesLimit` is `0`, or `CachingEnabled` is `false`, do not set the `disk-policy` attribute. An `IllegalStateException` is thrown if the attribute is set. + +This declaration causes LRU to overflow to disk: + +``` pre +<region-attributes lru-entries-limit="20000" + disk-policy="overflows"> + <persistence-manager ... /> +</region-attributes> +``` + +Overflow requires a persistence manager for cache-to-disk and disk-to-cache operations. See [PersistenceManager](persistence-manager.html#persistence-manager). + +## <a id="disk-policy__section_FE325E59644149ACA43DA2ABB4CF0F7A" class="no-quick-link"></a>Overflowing Data to Disk + +Region data can be stored to disk using the overflow process to satisfy region capacity restrictions without completely destroying the local cache data. The storage mechanism uses disk files to hold region entry data. When an entry is overflowed, its value is written to disk but its key and entry object remain in the cache. This also uses the region attribute [DiskPolicy](disk-policy.html#disk-policy). + +Overflow allows you to keep the region within a user-specified size in memory by relegating the values of least recently used (LRU) entries to disk. Overflow essentially uses disk as a swap space for entry values. When the region size reaches the specified threshold, entry values are moved from memory to disk, as shown in the following figure. If an entry is requested whose value is only on disk, the value is copied back into memory, possibly causing the value of a different LRU entry to be overflowed to disk. + +<a id="disk-policy__fig_67963EC3BDD64272BBDAD9517E1D78A0"></a> + +<span class="figtitleprefix">Figure: </span>Data Flow Between Overflow Region and Disk Files + +<img src="../common/images/client-cache-data-flow.gif" alt="Data Flow Between Overflow Region and Disk Files" id="disk-policy__image_687021ECD97A40FB843DBDE59C555384" class="image" /> + +In this figure the value of the LRU entry X has been moved to disk to recover space in memory. The key for the entry remains in memory. From the distributed system perspective, the value on disk is as much a part of the region as the data in memory. A `get` performed on region B looks first in memory and then on disk as part of the local cache search. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/entries.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/entries.html.md.erb b/geode-docs/nativeclient/client-cache/entries.html.md.erb new file mode 100644 index 0000000..b5799f5 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/entries.html.md.erb @@ -0,0 +1,20 @@ +--- +title: Region Entries +--- + +Region entries hold cached application data. Entries are automatically managed according to region attribute settings. + +You can create, update, invalidate, and destroy entries through explicit API calls or through operations distributed from other caches. + +When the number of entries is very large, a partitioned region can provide the required data management capacity if the total size of the data is greater than the heap in any single JVM. + +When an entry is created, a new object is instantiated in the region containing: + +- The entry key. +- The entry value. This is the application data object. The entry value may be set to `NULL`, which is the equivalent of an invalid value. + +Entry operations invoke callbacks to user-defined application plug-ins. In this chapter, the calls that may affect the entry operation itself (by providing a value or aborting the operation, for example) are highlighted, but all possible interactions are not listed. For details, see [Application Plug-Ins](application-plugins.html#application-plugins). + +`DateTime` objects must be stored in the cache in UTC, so that times correspond between client and server. If you use a date with a different time zone, convert it when storing into and retrieving from the cache. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/expiration-attributes.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/expiration-attributes.html.md.erb b/geode-docs/nativeclient/client-cache/expiration-attributes.html.md.erb new file mode 100644 index 0000000..d154d62 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/expiration-attributes.html.md.erb @@ -0,0 +1,65 @@ +--- +title: Specifying Expiration Attributes +--- + +<a id="expiration-attributes__section_4901B92DE7EB408F81792920C9E4ED7C"></a> +Expiration attributes govern the automatic eviction of regions and region entries from the cache. Eviction is based on the time elapsed since the last update or access to the object. This is referred to as the least-recently-used (LRU) eviction process. Expiration options range from marking the expired object as invalid to completely removing it from the distributed cache. Eviction can help keep data current by removing outdated entries, prompting a reload the next time they are requested. Eviction may also be used to recover space in the cache by clearing out unaccessed entries and regions. + +Similar to application plug-ins, expiration activities are hosted by each application that defines a region in its cache. + +The following example shows a declaration that causes the region's entries to be invalidated in the local cache after they have not been accessed for one minute. + +``` pre +<region-attributes> + <entry-idle-time> + <expiration-attributes timeout="60" action="local-invalidate"/> + </entry-idle-time> +</region-attributes> +``` + +Region and region entry expiration attributes are set at the region level. By default, regions and entries do not expire. The following attributes cover two types of expiration: time-to-live (TTL) and idle timeout. + +<table> +<colgroup> +<col width="50%" /> +<col width="50%" /> +</colgroup> +<tbody> +<tr class="odd"> +<td><code class="ph codeph">RegionTimeToLive</code></td> +<td>Number of seconds that the region remains in the cache after the last creation or update before the expiration action occurs.</td> +</tr> +<tr class="even"> +<td><code class="ph codeph">EntryTimeToLive</code></td> +<td>For entries, the counter is set to zero for <code class="ph codeph">create</code> and <code class="ph codeph">put</code> operations. Region counters are reset when the region is created and when an entry has its counter reset. An update to an entry causes the time-to-live (TTL) counters to be reset for the entry and its region.</td> +</tr> +<tr class="odd"> +<td><code class="ph codeph">RegionIdleTimeout</code></td> +<td>Number of seconds that the region remains in the cache after the last access before the expiration action occurs.</td> +</tr> +<tr class="even"> +<td><code class="ph codeph">EntryIdleTimeout</code></td> +<td>The idle timeout counter for an object is reset when its TTL counter is reset. An entry's idle timeout counter is also reset whenever the entry is accessed through a <code class="ph codeph">get</code> operation. +<p>The idle timeout counter for a region is reset whenever the idle timeout is reset for one of its entries.</p></td> +</tr> +</tbody> +</table> + +## <a id="expiration-attributes__section_F338C1117B7B44398F59523B881EDD55" class="no-quick-link"></a>Using Statistics to Measure Expiration + +Expiration is measured by comparing expiration attribute settings with the last accessed time and last modified time statistics. These statistics are directly available to applications through the `CacheStatistics` object that is returned by the `Region::getStatistics` and `RegionEntry::getStatistics` functions. The `CacheStatistics` object also provides a function for resetting the statistics counters. + +## <a id="expiration-attributes__section_6B402F97ECD8492A8798AC838D0BB606" class="no-quick-link"></a>Expiration Actions + +You can specify one of the following actions for each expiration attribute: + +- **Destroy**. Removes the object completely from the cache. For regions, all entries are destroyed as well. Destroy actions are distributed according to the region's distribution settings. +- **Invalidate**. Marks the object as invalid. For entries, the value is set to `NULL`. You invalidate a region by invalidating all its entries. Invalidate actions are distributed according to the region's distribution settings. When an entry is invalid, a `get` causes the cache to retrieve the entry according to the steps described in [Entry Retrieval](accessing-entries.html#accessing-entries__section_AD6AFD842C144C128FA1C7F0B9283372). +- **Local destroy**. Destroys the object in the local cache but does not distribute the operation. +- **Local invalidate**. Invalidates the object in the local cache but does not distribute the operation. + **Note:** + Destruction and invalidation cause the same event notification activities whether carried out explicitly or through expiration activities. + +## <a id="expiration-attributes__section_57F5B32CE9B34F29907E8697F51817F9" class="no-quick-link"></a>Region Expiration + +Expiration activities in distributed regions can be distributed or performed only in the local cache. So one cache could control region expiration for a number of caches in the distributed system. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/getting-the-region-size.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/getting-the-region-size.html.md.erb b/geode-docs/nativeclient/client-cache/getting-the-region-size.html.md.erb new file mode 100644 index 0000000..d7d80d8 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/getting-the-region-size.html.md.erb @@ -0,0 +1,11 @@ +--- +title: Getting the Region Size +--- + +The `Region` API provides a `size` method (`Size` property for .NET) that gets the size of a region. + +For native client regions, this gives the number of entries in the local cache, not on the servers. + +See the `Region` API documentation for details. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/initial-capacity.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/initial-capacity.html.md.erb b/geode-docs/nativeclient/client-cache/initial-capacity.html.md.erb new file mode 100644 index 0000000..18f96d9 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/initial-capacity.html.md.erb @@ -0,0 +1,15 @@ +--- +title: InitialCapacity +--- + +<a id="initial-capacity__section_AB0163B072DA4DA0B858293CA02E91A1"></a> +Use this attribute, together with the `LoadFactor` attribute, to set the initial parameters on the underlying hashmap that stores region entries. This is the number of entries that the region map will be ready to hold when it is created. + +This declaration sets the region's initial capacity to `10000`: + +``` pre +<region-attributes initial-capacity="10000"> +</region-attributes> +``` + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/invalidating-cached-entries.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/invalidating-cached-entries.html.md.erb b/geode-docs/nativeclient/client-cache/invalidating-cached-entries.html.md.erb new file mode 100644 index 0000000..e13ac0b --- /dev/null +++ b/geode-docs/nativeclient/client-cache/invalidating-cached-entries.html.md.erb @@ -0,0 +1,16 @@ +--- +title: Invalidating or Destroying Cached Entries +--- + +<a id="invalidating-cached-entries__section_9244FABA5204452A8D25D1184310B7EE"></a> +Invalidating an entry sets the entry's value to `NULL`. Destroying it removes the entry from the region altogether. These operations can be carried out in the local cache in the following ways: + +- Through direct API calls from the client. +- Through expiration activities based on the entry's statistics and the region's attribute settings. + +**Note:** +A user-defined cache writer is called before an operation is completed, and can abort an entry destroy operation. + +Whether carried out explicitly or through expiration activities, invalidation and destruction cause event notification: The `CacheEvent` object has an `isExpiration` flag that is set to true for events resulting from expiration activities, and set to `false` for all other events. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/invalidating-region.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/invalidating-region.html.md.erb b/geode-docs/nativeclient/client-cache/invalidating-region.html.md.erb new file mode 100644 index 0000000..0769681 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/invalidating-region.html.md.erb @@ -0,0 +1,25 @@ +--- +title: Invalidating and Destroying Regions +--- + +Invalidation marks all entries contained in the region as invalid (with null values). Destruction removes the region and all of its contents from the cache. + +<a id="invalidating-region__section_6F7E304D1D5743F1B53FCBD4F82651D0"></a> +You can execute these operations explicitly in the local cache in the following ways: + +- Through direct API calls from the native client. +- Through expiration activities based on the region's statistics and attribute settings. + +In either case, you can perform invalidation and destruction as a local or a distributed operation. + +- A local operation affects the region only in the local cache. +- A distributed operation works first on the region in the local cache and then distributes the operation to all other caches where the region is defined. This is the proper choice when the region is no longer needed, or valid, for any application in the distributed system. +- If the region on the server is configured as a partitioned region, it cannot be cleared using API calls from the native client. + +A user-defined cache writer can abort a region destroy operation. Cache writers are synchronous listeners with the ability to abort operations. If a cache writer is defined for the region anywhere in the distributed system, it is invoked before the region is explicitly destroyed. + +Region invalidation and destruction can cause other user-defined application plug-ins to be invoked as well. These plug-ins are described in detail in [Application Plug-Ins](application-plugins.html#application-plugins). + +Whether carried out explicitly or through expiration activities, invalidation and destruction cause event notification. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/load-factor.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/load-factor.html.md.erb b/geode-docs/nativeclient/client-cache/load-factor.html.md.erb new file mode 100644 index 0000000..7643702 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/load-factor.html.md.erb @@ -0,0 +1,15 @@ +--- +title: LoadFactor +--- + +<a id="load-factor__section_D4102F0D396E4E2DA05654A20FA0723D"></a> +Use this attribute, together with the `InitialCapacity` attribute, to set the initial parameters on the underlying hashmap that stores region entries. When the number of entries in the map exceeds the `LoadFactor` times current capacity, the capacity is increased and the map is rehashed. You get the best performance if you configure a properly sized region at the start and do not have to rehash it. + +This declaration sets the region's load factor to `0.75` : + +``` pre +<region-attributes load-factor="0.75"> +</region-attributes> +``` + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/lru-entries-limit.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/lru-entries-limit.html.md.erb b/geode-docs/nativeclient/client-cache/lru-entries-limit.html.md.erb new file mode 100644 index 0000000..8f716e5 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/lru-entries-limit.html.md.erb @@ -0,0 +1,31 @@ +--- +title: LruEntriesLimit +--- + +<a id="concept_75D723D60E044FF9AE97C939699AB10A__section_B0174EA802CB47C9981EF3BDF4B7D169"></a> +This attribute sets the maximum number of entries to hold in a caching region. When the capacity of the caching region is exceeded, a least-recently-used (LRU) algorithm is used to evict entries. + +**Note:** +This is a tuning parameter that affects system performance. + +When eviction is configured, memory consumption or entry count is monitored and, when capacity is reached, Geode makes way for new entries by removing or overflowing the stalest LRU entries to disk. + +If you use disk data overflow to supplement memory for your data cache, make sure you have enough disk space to store the data. + +This declaration limits the region to 20,000 entries: + +``` pre +<region-attributes lru-entries-limit="20000" + initial-capacity="20000" + load-factor="1"> +</region-attributes> +``` + +Evicted entries can be destroyed or moved to disk as an extension of the cache. See [DiskPolicy](disk-policy.html#disk-policy). + +**Note:** +When `CachingEnabled` is `false`, do not set the `LruEntriesLimit` attribute. An `IllegalStateException` is thrown if the attribute is set. + +See also [Controlling Cache Size](controlling-cache-size.html#controlling-cache-size). + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/managing-lifetime-cached-object.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/managing-lifetime-cached-object.html.md.erb b/geode-docs/nativeclient/client-cache/managing-lifetime-cached-object.html.md.erb new file mode 100644 index 0000000..0eb18d4 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/managing-lifetime-cached-object.html.md.erb @@ -0,0 +1,48 @@ +--- +title: Managing the Lifetime of a Cached Object +--- + +All cacheable objects derive from `SharedBase` , which provides reference counting. Cacheable objects are referenced using `SharedPtr` types. + +<a id="managing-lifetime-cached-object__section_5F8E6FE4F9AB4C658516DB0D31DD4FF8"></a> +When `SharedPtr` retrieves a cached object, the object remains alive as long as that pointer or the cache itself references the object. + +A native client may have many pointers that reference an object. Regardless of how many pointers to the object are deleted, the object remains alive until the last remaining pointer is deleted. At that point the object is deleted. + +This is a very simple example: + +``` pre +CacheableStringPtr p = CacheableString::create("string"); +region.put("key", p) ; +``` + +In the example: + +- The act of object creation allocates memory and initializes the object. +- When you assign the object to a `SharedPtr` , you relinquish control of the lifetime of that object to the reference counting mechanism for the cache. +- The put operation does not actually copy the object into the cache. Rather, it copies a `SharedPtr` into the cache's hashmap. Consequently, the object remains alive in the cache when the original `SharedPtr` goes away. + +The client can make use of an object after you have initialized the object. For example, another `SharedPtr` might issue a `get` to retrieve the object from the cache: + +``` pre +CacheableStringPtr p2 = region.get("key"); +``` + +Because `p` (the original `SharedPtr`) and `p2` point to the same object in memory, it is possible under some circumstances for multiple `SharedPtr` types to work on the same object in data storage. + +**Note:** +Once you have put an object into the cache, do not delete it explicitly. Attempting to do so can produce undesirable results. + +## <a id="managing-lifetime-cached-object__section_8753DE6DF3864BEC806D39F623CBE3E0" class="no-quick-link"></a>Changed Objects + +If an object update is received, the cache no longer holds the same object. Rather, it holds a completely different instance of the object. The client does not see the updates until it calls a `get` to fetch the object again from the local cache, or (in a cache plug-in) calls `EntryEvent::getNewValue`. + +For more about plug-ins, see [Application Plug-Ins](application-plugins.html#application-plugins). + +## <a id="managing-lifetime-cached-object__section_065526A7FFBB464591A5E119EB8D6CA6" class="no-quick-link"></a>Object Expiration + +When a cache automatically deletes an object as a result of an expiration action, the reference counting pointers protect the client from situations that might otherwise result if the cache actually freed the object's memory. Instead, the client disconnects the object from the cache by deleting the cache's `SharedPtr` reference, while leaving untouched any client threads with a `SharedPtr` to that object. + +## <a id="managing-lifetime-cached-object__section_6D700999EE534BD7999D5B428301F5A6" class="no-quick-link"></a>Object Lifetime Across the Distributed Cache + +An object remains alive until every copy of the object is gone. In distributed regions, expiration activities can be local or distributed, depending on a region's distribution settings. One cache could control the expiration of all copies of an object in all the caches in the distributed system. Alternatively, each cache could control the expiration of its own local copy of the object. If the configuration gives each cache local control, and the expiration parameters are set to different lengths of time in different caches, some copies of an object may still exist after it has disappeared in other caches. See [Expiration Attributes](expiration-attributes.html#expiration-attributes) for more information. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/notification-for-operations.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/notification-for-operations.html.md.erb b/geode-docs/nativeclient/client-cache/notification-for-operations.html.md.erb new file mode 100644 index 0000000..0abfdcb --- /dev/null +++ b/geode-docs/nativeclient/client-cache/notification-for-operations.html.md.erb @@ -0,0 +1,16 @@ +--- +title: Notification for Operations +--- + +<a id="notification-for-operations__section_53F43C51118C4087915CB954CA3439E0"></a> +Listeners are invoked for client-initiated operations only after the client operation succeeds on the server. Listener invocation on the client indicates that the server has the same data as the client. + +If a client operation fails on the server, the operation is rolled back, assuming that no other thread has modified the data in the intervening period. Rollback may not be possible in cases where the entry has been evicted by LRU or expiration during this period. Thus when an exception is received from the server for an operation, local changes may not have been rolled back + +## <a id="notification-for-operations__section_48240559E20D4FAF8FDEC8D62C098357" class="no-quick-link"></a>Event Notification Sequence + +Events received on the clients that originated on the server invoke the subscription for the event as seen by the server. Events originating on the client invoke the subscription as seen by the client. + +For example, a client that receives a `create` and an `update` from the server fires a `create` event and an `update` event because that is how the server saw it. A cacheless client that does two consecutive put operations has two `afterCreate` events invoked on the originating client because the client does not have any history about the first put , since it is cacheless. + +For the same sequence, the server sees an `afterCreate` and an `afterUpdate` event, and a remote client receiving the event sees an `afterCreate` followed by an `afterUpdate` event. A client that caches locally sees an `afterCreate` and an `afterUpdate` for the same scenario (as will the server and remote clients). http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/overview-client-cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/overview-client-cache.html.md.erb b/geode-docs/nativeclient/client-cache/overview-client-cache.html.md.erb new file mode 100644 index 0000000..30689db --- /dev/null +++ b/geode-docs/nativeclient/client-cache/overview-client-cache.html.md.erb @@ -0,0 +1,24 @@ +--- +title: About the Native Client Cache +--- + +The cache consists of data regions, each of which can contain any number of entries. Region entries hold the cached data. Every entry has a key that uniquely identifies it within the region and a value where the data object is stored. + +The `Cache` instance allows your process to set general parameters for communication between a cache and other caches in the distributed system, and to create and access any region in the cache. + +Regions are created from the `Cache` instance. Regions provide the entry point to the interfaces for instances of `Region` and `RegionEntry`. + +## <a id="native-client-cache__section_A0F2E9EF30324736BD0D5F92FE3D1BD7" class="no-quick-link"></a>Main Features and Functionality + +The native client cache provides the following features and functionality. + +- Local and distributed data caching for fast access. +- Data distribution between applications on the same or different platforms. +- Local and remote data loading through application plug-ins. +- Application plug-ins for synchronous and asynchronous handling of data events. +- Automated and application-specific data eviction for freeing up space in the cache, including optional overflow to disk. +- System message logging, and statistics gathering and archiving. + +For more information specific to your client programming language, see the online API documentation and [Working with the C++ API](../cpp-caching-api/cpp-caching-api.html#concept_CEC658A999414AC3A494578C214BF64E) and [Working with the .NET Caching API](../dotnet-caching-api/dotnet-caching-api.html#concept_FC6776DCE6ED48B887A6137761104AA4). + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/persistence-manager.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/persistence-manager.html.md.erb b/geode-docs/nativeclient/client-cache/persistence-manager.html.md.erb new file mode 100644 index 0000000..1d71808 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/persistence-manager.html.md.erb @@ -0,0 +1,224 @@ +--- +title: PersistenceManager +--- + +For each region, if the disk-policy attribute is set to overflows, a persistence-manager plug-in must perform cache-to-disk and disk-to-cache operations. See [Application Plug-Ins](application-plugins.html#application-plugins). + +Persistence manager declaration: + +``` pre +<region-attributes lru-entries-limit="nnnnn" + disk-policy="overflows"> + <persistence-manager library-name="libraryName" + library-function-name="functionName"> + <properties> + <property name="propertyName" value="propertyValue" /> + </properties> + </persistence-manager> +</region-attributes> +``` + +The optional properties set parameters for the plug-in. + + +## <a id="persistence-manager__section_9FC7089FDF8044868F17A2659397402A" class="no-quick-link"></a>Using SQLite as a Persistence Manager + +The Geode native client distribution includes a persistence manager that uses the open-source SQLite library. + +SQLite is a software library that implements a self-contained transactional SQL database. SQLite does not require its own server or separate configuration, and the source code for SQLite is in the public domain. For more information on SQLite, see [http://www.sqlite.org](http://www.sqlite.org). + +Each SQLite persistence manager persists its region data in a SQLite database that is stored in disk files. In a given native client application process, each region must have a unique persistence (overflow) directory. + +<a id="persistence-manager__fig_6A0C9F1A29134ACBA0FDD8236CD836B6"></a> +<span class="figtitleprefix">Figure: </span>SQLite Database Persistence Manager Directory Structure + +<img src="../../images/SQLite_Persistence_Mgr.png" id="persistence-manager__image_BD1AF915E09548D68D9307E2F52737F9" class="image" /> + +## <a id="persistence-manager__section_3C6991A39C5F4FB8A945EF15FB089287" class="no-quick-link"></a>SQLite Persistence Manager Region Attributes + +The following table describes the region attributes that can be configured for the SQLite persistence manager. + +| Property | Description | Default Setting | +|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| PersistenceDirectory | Directory where each region's database files are stored. This setting must be different for each region including regions in different processes. This directory is created by the persistence manager. The persistence manager fails to initialize if this directory already exists or cannot be created. | Default is to create a subdirectory named GemFireRegionData in the directory where the process using the region was started. | +| PageSize | Maximum page size of the SQLite database. SQLite can limit the size of a database file to prevent the database file from growing too large and consuming too much disk space. | Ordinarily, if no value is explicitly provided, SQLite creates a database with the page size set to SQLITE\_DEFAULT\_PAGE\_SIZE (default is 1024). However, based on certain device characteristics (for example, sector-size and atomic write() support) SQLite may choose a larger value. PageSize specifies the maximum value that SQLite will be able to choose on its own. See <a href="http://www.sqlite.org/compile.html#default_page_size";>http://www.sqlite.org/compile.html#default_page_size</a>. for more details on SQLITE\_DEFAULT\_PAGE\_SIZE. | +| MaxPageCount | Maximum number of pages in one database file. | SQLite default, which is 1073741823. | + +## <a id="persistence-manager__section_A9583FBEB5D74B92AD61CB6158AE2B4C" class="no-quick-link"></a>Configuring the SQLite Persistence Manager Plug-In for C++ Applications + +To load the SQLite persistence manager plug-in for C++ applications, you can configure it either in your client's `cache.xml` or programmatically using the native client C++ API. + +The following is an example of how to specify the following region attributes in your client's cache.xml: + +``` pre +<region-attributes> + <persistence-manager library-name="libSqLiteImpl.so" library-function-name="createSqLiteInstance"> + <properties> + <property name="PersistenceDirectory" value="/xyz"/> + <property name="PageSize" value="65536"/> + <property name="MaxPageCount" value="1073741823"/> + </properties> + </persistence-manager> +</region-attributes> +``` + +## C++ API Example + +To use the native client C++ API, set SQLite persistence manager attributes programmatically as follows: + +``` pre +PropertiesPtr sqliteProperties = Properties::create(); +sqliteProperties->insert("MaxPagecount", "5"); +sqliteProperties->insert("PageSize", "1024"); +sqliteProperties->insert("PersistenceDirectory", "SqLite-Test779"); +regionFactory->setPersistenceManager("SqLiteImpl","createSqLiteInstance", + sqliteProperties); +``` + +## <a id="persistence-manager__section_7410F68E0BB144A584A9AFE7E8CDBE22" class="no-quick-link"></a>Configuring the SQLite Persistence Manager Plug-In for .NET Applications + +To load the SQLite persistence manager plug-in for .NET applications, you can configure it either in your client's cache.xml or programmatically using the .NET API: + +``` pre +<persistence-manager library-name="Gemstone.Gemfire.Plugins.SqLite" + library-function-name="GemStone.GemFire.Plugins.SqLite.SqLiteImpl<System.Object, System.Object>.Create"> + <properties> + <property name="PersistenceDirectory" value="SqLite"/> + <property name="MaxPageCount" value="1073741823"/> + <property name="PageSize" value="65536"/> + </properties> +</persistence-manager> +``` + +## .NET API Example + +To use the native client .NET API, set the SQLite persistence manager attributes programmatically as follows: + +``` pre +Properties<string, string> sqliteProperties = new Properties<string, string>(); +sqliteProperties.Insert("PageSize", "65536"); +sqliteProperties.Insert("MaxFileSize", "51200000"); +sqliteProperties.Insert("PersistenceDirectory", SqLiteDir); +rf.SetPersistenceManager("Gemstone.Gemfire.Plugins.SqLite", +"Gemstone.Gemfire.Plugins.SqLiteSqLiteImpl<System.Object,System.Object>.Create", +sqliteProperties); +``` + +You can also use and configure the C++ SQLite persistence manager library from your .NET application as follows: + +``` pre +rf.SetPersistenceManager("SqliteImpl", "createSqLiteInstance", sqliteProperties); +``` + +## <a id="persistence-manager__section_9D038C438E01415EA4D32000D5CB5596" class="no-quick-link"></a>Implementing a PersistenceManager with the IPersistenceManager Interface + +When developing .NET managed applications, you can use the IPersistenceManager managed interface to implement your own persistence manager. The following code sample provides the IPersistenceManager interface: + +``` pre +/// <summary> +/// IPersistenceManager interface for persistence and overflow. +/// This class abstracts the disk-related operations in case of persistence or overflow to disk. +/// A specific disk storage implementation will implement all the methods described here. +/// </summary> +generic<class TKey, class TValue> +public interface class IPersistenceManager + { + public: + /// <summary> + /// Called after an implementation object is created. Initializes all the implementation specific environments needed. + /// </summary> + /// <param name="region"> + /// Region for which this PersistenceManager is initialized. + /// </param> + /// <param name="diskProperties"> + /// Configuration Properties used by PersistenceManager implementation. + /// </param> + void Init(IRegion<TKey, TValue>^ region, Properties<String^, String^>^ diskProperties); + + /// <summary> + /// Writes a key, value pair of region to the disk. The actual file or database related write operations should be implemented in this method. + /// </summary> + /// <param name="key"> + /// the key to write. + /// </param> + /// <param name="value"> + /// the value to write. + /// </param> + void Write(TKey key, TValue value); + + /// <summary> + /// This method is not used. + /// </summary> + bool WriteAll(); + + /// <summary> + /// Reads the value for the key from the disk. + /// </summary> + /// <param name="key"> + /// key for which the value has to be read. + /// </param> + TValue Read(TKey key); + + /// <summary> + /// This method is not used. + /// </summary> + bool ReadAll(); + + /// <summary> + /// Destroys the entry specified by the key in the argument. + /// </summary> + /// <param name="key"> + /// key of the entry which is being destroyed. + /// </param> + void Destroy(TKey key); + + /// <summary> + /// Closes the persistence manager instance. + /// </summary> + void Close(); +} +``` + +The following is a sample interface implementation: + +``` pre +class MyPersistenceManager<TKey, TValue> : IPersistenceManager<TKey, TValue> + { + #region IPersistenceManager<TKey,TValue> Members + public void Close() + { + throw new NotImplementedException(); + } + + public void Destroy(TKey key) + { + throw new NotImplementedException(); + } + + public void Init(IRegion<TKey, TValue> region, Properties<string, string> disk Properties) + { + throw new NotImplementedException(); + } + + public TValue Read(TKey key) + { + throw new NotImplementedException(); + } + + public void Write(TKey key, TValue value) + { + throw new NotImplementedException(); + } + + public bool ReadAll() + { + throw new NotImplementedException(); + } + + public bool WriteAll() + { + throw new NotImplementedException(); + } + #endregion + } +``` http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/programmatic-region-creation.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/programmatic-region-creation.html.md.erb b/geode-docs/nativeclient/client-cache/programmatic-region-creation.html.md.erb new file mode 100644 index 0000000..f3f8757 --- /dev/null +++ b/geode-docs/nativeclient/client-cache/programmatic-region-creation.html.md.erb @@ -0,0 +1,24 @@ +--- +title: Programmatic Region Creation +--- + +You create regions programmatically with the `regionFactory` class. + +**Note:** +Before creating a region, specify region attributes. See [Region Attributes](region-attributes.html#region-attributes). + +Create your regions using the `regionFactory` class. + +**C++ RegionFactory Example** + +``` pre +RegionFactoryPtr regionFactory = + cachePtr->createRegionFactory(CACHING_PROXY); +RegionPtr regPtr0 = regionFactory->setLruEntriesLimit(20000) + ->create("exampleRegion0"); + +``` + +**Note:** For more information on how to create a region, see [Working with the C++ API](../cpp-caching-api/cpp-caching-api.html#concept_CEC658A999414AC3A494578C214BF64E), [Working with the .NET API](../dotnet-caching-api/dotnet-caching-api.html#concept_FC6776DCE6ED48B887A6137761104AA4), and the native client API reference. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/nativeclient/client-cache/region-access.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/nativeclient/client-cache/region-access.html.md.erb b/geode-docs/nativeclient/client-cache/region-access.html.md.erb new file mode 100644 index 0000000..efb6fee --- /dev/null +++ b/geode-docs/nativeclient/client-cache/region-access.html.md.erb @@ -0,0 +1,21 @@ +--- +title: Region Access +--- + +You can use `Cache::getRegion` to retrieve a reference to a specified region. + +`RegionPtr` returns `NULL` if the region is not already present in the application's cache. A server region must already exist. + +A region name *cannot* contain these characters: + +- < +- > +- : +- " +- / +- \\ +- | +- ? +- \* + +
