Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 3DB14200C1B for ; Tue, 14 Feb 2017 20:40:04 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id 3C35F160B6A; Tue, 14 Feb 2017 19:40:04 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 5E9A9160B5F for ; Tue, 14 Feb 2017 20:39:58 +0100 (CET) Received: (qmail 77172 invoked by uid 500); 14 Feb 2017 19:39:48 -0000 Mailing-List: contact commits-help@geode.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@geode.apache.org Delivered-To: mailing list commits@geode.apache.org Received: (qmail 75474 invoked by uid 99); 14 Feb 2017 19:39:47 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 14 Feb 2017 19:39:47 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 1D391E0A2C; Tue, 14 Feb 2017 19:39:47 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: abaker@apache.org To: commits@geode.apache.org Date: Tue, 14 Feb 2017 19:40:50 -0000 Message-Id: <9bfc7a0d506d4e7795f778ed6e68b39c@git.apache.org> In-Reply-To: <158ab04503fe4d86bd018fa4a2e277af@git.apache.org> References: <158ab04503fe4d86bd018fa4a2e277af@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [66/74] [abbrv] geode-native git commit: GEODE-1964 Move doc files to geode-native subdirectory, add geode-native-book directory, update User Guide sources for donation 2 archived-at: Tue, 14 Feb 2017 19:40:04 -0000 http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/dotnet-caching-api/serialize-using-ipdxserializable.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/dotnet-caching-api/serialize-using-ipdxserializable.html.md.erb b/geode-docs/docs/geode-native-docs/dotnet-caching-api/serialize-using-ipdxserializable.html.md.erb new file mode 100644 index 0000000..a4138fa --- /dev/null +++ b/geode-docs/docs/geode-native-docs/dotnet-caching-api/serialize-using-ipdxserializable.html.md.erb @@ -0,0 +1,103 @@ +--- +title: Serialize Using the GemFire IPdxSerializable Interface +--- + +Use this procedure to program your domain object for PDX serialization using the `IPdxSerializable` Interface. When you write objects using PDX serialization, they are distributed to the server tier in PDX serialized form. When you run queries against the objects on the servers, only the fields you specify are deserialized. + +**Procedure** + +1. In your domain class, implement `GemStone::GemFire::Cache::Generic::IPdxSerializable`. Example: + + ``` pre + using GemStone.GemFire.Cache.Generic; + ... + public class PortfolioPdx : IPdxSerializable + ``` + +2. If your domain class does not have a zero-arg constructor, create one for it. + + If you also use PDX serialization in Java for the object, serialize the object in the same way for each language. Serialize the same fields in the same order and mark the same identify fields. + +3. Program the `IPdxSerializable ToData` function to serialize your object as required by your application. + 1. Write your domain class's standard .NET data fields using the `IPdxWriter` write methods. GemFire automatically provides `IPdxWriter` to the `ToData` function for `IPdxSerializable` objects. + 2. Call the `ToData markIdentifyField` function for each field GemFire should use to identify your object. This is used to compare objects for operations like `DISTINCT` queries. The `markIdentifyField` call must come after the associated field write methods. + + Example: + + ``` pre + // object fields + private int m_id; + private string m_pkid; + private PositionPdx m_position1; + private PositionPdx m_position2; + private Hashtable m_positions; + private string m_type; + private string m_status; + private string[] m_names; + private byte[] m_newVal; + private DateTime m_creationDate; + private byte[] m_arrayZeroSize; + private byte[] m_arrayNull; + // ToData + public void ToData(IPdxWriter writer) + { + writer.WriteInt("id", m_id) + //identity field + .MarkIdentityField("id") + .WriteString("pkid", m_pkid) + .WriteObject("position1", m_position1) + .WriteObject("position2", m_position2) + .WriteObject("positions", m_positions) + .WriteString("type", m_type) + .WriteString("status", m_status) + .WriteStringArray("names", m_names) + .WriteByteArray("newVal", m_newVal) + .WriteDate("creationDate", m_creationDate) + .WriteByteArray("arrayNull", m_arrayNull) + .WriteByteArray("arrayZeroSize", m_arrayZeroSize); + } + ``` + +4. Program `IPdxSerializable FromData` to read your data fields from the serialized form into the object's fields using the `IPdxReader` read methods. GemFire automatically provides `IPdxReader` to the `FromData` function for `IPdxSerializable` objects. + + Use the same names as you did in `ToData` and call the read operations in the same order as you called the write operations in your `ToData` implementation. + + Example: + + ``` pre + public void FromData(IPdxReader reader) + { + m_id = reader.ReadInt("id"); + + bool isIdentity = reader.IsIdentityField("id"); + + if (isIdentity == false) + throw new IllegalStateException("Portfolio id is identity field"); + + bool isId = reader.HasField("id"); + + if (isId == false) + throw new IllegalStateException("Portfolio id field not found"); + + bool isNotId = reader.HasField("ID"); + + if (isNotId == true) + throw new IllegalStateException("Portfolio isNotId field found"); + + m_pkid = reader.ReadString("pkid"); + m_position1 = (PositionPdx)reader.ReadObject("position1"); + m_position2 = (PositionPdx)reader.ReadObject("position2"); + m_positions = (Hashtable)reader.ReadObject("positions"); + m_type = reader.ReadString("type"); + m_status = reader.ReadString("status"); + m_names = reader.ReadStringArray("names"); + m_newVal = reader.ReadByteArray("newVal"); + m_creationDate = reader.ReadDate("creationDate"); + m_arrayNull = reader.ReadByteArray("arrayNull"); + m_arrayZeroSize = reader.ReadByteArray("arrayZeroSize"); + } + ``` + +5. Optionally, program your domain object's equals and hashcode methods. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/dotnet-caching-api/serializing-domain-objects.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/dotnet-caching-api/serializing-domain-objects.html.md.erb b/geode-docs/docs/geode-native-docs/dotnet-caching-api/serializing-domain-objects.html.md.erb new file mode 100644 index 0000000..c25b28f --- /dev/null +++ b/geode-docs/docs/geode-native-docs/dotnet-caching-api/serializing-domain-objects.html.md.erb @@ -0,0 +1,29 @@ +--- +title: Serialize Your Domain Objects with IPdxSerializer +--- + +For domain objects that you cannot or do not want to modify, use the `IPdxSerializer` class to serialize and deserialize the object's fields. + +You use one `IPdxSerializer` implementation for the entire cache, programming it for all of the domain objects that you handle in this way. This way you do not have to implement the `IPdxSerializable` interface for each domain class. + +With `IPdxSerializer`, you leave your domain object as-is and handle the serialization and deserialization in the separate serializer. You register the serializer in your cache PDX configuration. Then program the serializer to handle all of the domain objects you need. + +If you write your own `IPdxSerializer` and you also use the `ReflectionBasedAutoSerializer`, then the `IPdxSerializer` needs to own the `ReflectionBasedAutoSerializer` and delegate to it. A cache can only have a single `IPdxSerializer` instance. + +**Note:** +The `IPdxSerializer` `toData` and `fromData` methods differ from those for `IPdxSerializable`. They have different parameters and results. + +To register an `IPdxSerializer`, you can use the following code. Note that you can only register the `IPdxSerializer` in the application code. It cannot be configured declaratively in `cache.xml`. + +Example: + +``` pre +using GemStone.GemFire.Cache.Generic; +... +// Register a PdxSerializer to serialize +// domain objects using PDX serialization + +Serializable.RegisterPdxSerializer(new MyPdxSerializer()); +``` + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/dotnet-caching-api/simple-csharp-example.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/dotnet-caching-api/simple-csharp-example.html.md.erb b/geode-docs/docs/geode-native-docs/dotnet-caching-api/simple-csharp-example.html.md.erb new file mode 100644 index 0000000..d9f9949 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/dotnet-caching-api/simple-csharp-example.html.md.erb @@ -0,0 +1,43 @@ +--- +title: A Simple C# Example +--- + +An example shows how to connect to Geode, create a cache and region, put and get keys and values, and disconnect. + +## Simple C\# Code + +``` pre +class BasicOperations +{ + public static void Main(string[] args) + { + try + { + // 1. Create a cache + CacheFactory cacheFactory = CacheFactory.CreateCacheFactory(); + Cache cache = cacheFactory.Create(); + + // 2. Create default region attributes using region factory + RegionFactory regionFactory = + cache.CreateRegionFactory(RegionShortcut.CACHING_PROXY); + + // 3. Create a region + IRegion region = + regionFactory.Create("exampleRegion"); + + // 4. Put some entries + region[111] = "Value1"; + region[123] = "123"; + + // 5. Get the entries + string result1 = region[111]; + string result2 = region[123]; + + // 6. Close cache + cache.Close(); + } + } +} +``` + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/dotnet-caching-api/troubleshooting-dotnet-applications.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/dotnet-caching-api/troubleshooting-dotnet-applications.html.md.erb b/geode-docs/docs/geode-native-docs/dotnet-caching-api/troubleshooting-dotnet-applications.html.md.erb new file mode 100644 index 0000000..74dec75 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/dotnet-caching-api/troubleshooting-dotnet-applications.html.md.erb @@ -0,0 +1,25 @@ +--- +title: Troubleshooting .NET Applications +--- + +The .NET Framework does not find managed DLLs using the conventional `PATH` environment variable. In order for your assembly to find and load a managed DLL, it must either be loaded as a private assembly using `assemblyBinding`, or it must be installed into the Global Assembly Cache (GAC). + +The GAC utility must be run on every machine that runs the .NET code. + +If an assembly attempts to load the `GemStone.GemFire.Cache.dll` without meeting this requirement, you receive this `System.IO.FileNotFoundException`: + +``` pre +{{ + +Unhandled Exception: System.IO.FileNotFoundException: Could not load file +or assembly 'GemStone.GemFire.Cache, Version=8.0.0.0, Culture=neutral, +PublicKeyToken= 126e6338d9f55e0c' or one of its dependencies. The system +cannot find the file specified. +File name: 'GemStone.GemFire.Cache, Version=8.0.0.0, Culture=neutral, +PublicKeyT oken=126e6338d9f55e0c' +at HierarchicalClient.Main() + +}} +``` + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/dotnet-caching-api/using-ipdxinstancefactory.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/dotnet-caching-api/using-ipdxinstancefactory.html.md.erb b/geode-docs/docs/geode-native-docs/dotnet-caching-api/using-ipdxinstancefactory.html.md.erb new file mode 100644 index 0000000..6e7a82f --- /dev/null +++ b/geode-docs/docs/geode-native-docs/dotnet-caching-api/using-ipdxinstancefactory.html.md.erb @@ -0,0 +1,108 @@ +--- +title: Use the IPdxInstanceFactory to Create IPdxInstances +--- + +You can use the `IPdxInstanceFactory` to create an `IPdxInstance` from raw data when the domain class is not available on the server. + +This option can be useful when you need an instance of a domain class for plug-in code such as a function or a loader. If you have the raw data for the domain object (the class name and each field's type and data), then you can explicitly create a `IPdxInstance`. The `IPdxInstanceFactory` is very similar to the `IPdxWriter` except that after writing each field, you need to call the create method which returns the created `IPdxInstance.` + +## Creating an IPdxInstance with IPdxInstanceFactory + +``` pre +/* + * The PdxInstance QuickStart Example. + * This example takes the following steps: + * + * This example shows IPdxInstanceFactory and IPdxInstance usage. + * + * 1. Create a Cache. + * 2. Creates the PdxInstanceFactory for Person class. + * 3. Then creates instance of PdxInstance + * 4. It does put. + * 5. Then it does get and access it fields. + * 6. Close the Cache. + * +*/ +// Use standard namespaces +using System; +using System.Reflection; +// Use the GemFire namespace +using GemStone.GemFire.Cache.Generic; +namespace GemStone.GemFire.Cache.Generic.QuickStart { + public class Person { + private string name; + // this is the only field used on server to create hashcode + // and use in equals method + [PdxIdentityField] + private int id; + private int age; + public Person() { } + public Person(string name, int id, int age) { + this.name = name; + this.id = id; + this.age = age; + } + #region Public Properties + public string Name { + get { return name; } + } + public int ID { + get { return id; } + } + public int Age { + get { return age; } + } + #endregion + } + + // The PdxRemoteQuery QuickStart example. + class PdxInstance { + static void Main(string[] args) { + try { + CacheFactory cacheFactory = CacheFactory.CreateCacheFactory(null); + Console.WriteLine("Connected to the Distributed System"); + // Create a Cache with the "clientPdxRemoteQuery.xml" Cache XML file. + // Set SetPdxReadSerialized to true to access PdxInstance + Cache cache = cacheFactory.Set("cache-xml-file", + "XMLs/clientPdxInstance.xml").Create(); + Console.WriteLine("Created the Cache"); + // Get the example Region from the Cache which is declared + // in the Cache XML file. + IRegion region = + cache.GetRegion("Person"); + Console.WriteLine("Obtained the Region from the Cache"); + Person p = new Person("Jack", 7, 21); + //PdxInstanceFactory for Person class + IPdxInstanceFactory pif = cache.CreatePdxInstanceFactory("Person"); + pif.WriteString("name", p.Name); + pif.WriteInt("id", p.ID); + pif.MarkIdentityField("id"); + pif.WriteInt("age", p.Age); + IPdxInstance pdxInstance = pif.Create(); + Console.WriteLine("Created PdxInstance for Person class"); + region["Key1"] = pdxInstance; + Console.WriteLine("Populated PdxInstance Object"); + IPdxInstance retPdxInstance = region["Key1"]; + if ((int)retPdxInstance.GetField("id") == p.ID + && (int)retPdxInstance.GetField("age") == p.Age + && (string)retPdxInstance.GetField("name") == p.Name + && retPdxInstance.IsIdentityField("id") == true) + Console.WriteLine("PdxInstance returns all fields value expected"); + else + Console.WriteLine("PdxInstance doesn't returns all fields + value expected"); + + // Close the Cache. + cache.Close(); + Console.WriteLine("Closed the Cache"); + } + // An exception should not occur + catch (GemFireException gfex) { + Console.WriteLine("PdxSerializer Exception: {0}", gfex.Message); + } + } + } +} +``` + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/function-execution/data-aware-function-execution.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/function-execution/data-aware-function-execution.html.md.erb b/geode-docs/docs/geode-native-docs/function-execution/data-aware-function-execution.html.md.erb new file mode 100644 index 0000000..e0d2004 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/function-execution/data-aware-function-execution.html.md.erb @@ -0,0 +1,11 @@ +--- +title: Understanding Data-Aware Function Routing +--- + +Achieving linear scalability is predicated upon being able to horizontally partition the application data such that concurrent operations by distributed applications can be done independently across partitions. + +In other words, if the application requirements for transactions can be restricted to a single partition, and all data required for the transaction can be colocated to a single server member or a small subset of server members, then true parallelism can be achieved by vectoring the concurrent accessors to the ever-growing number of partitions. + +Most scalable enterprise applications grow in data volume, where the number of data items managed rather than the size of individual items grows over time. If the above logic holds (especially true for OLTP class applications), then we can derive sizable benefits by routing the data-dependent application code to the fabric member hosting the data. This routing of application code to the data of interest is called data-aware function routing, or behavior routing. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/function-execution/executing-functions.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/function-execution/executing-functions.html.md.erb b/geode-docs/docs/geode-native-docs/function-execution/executing-functions.html.md.erb new file mode 100644 index 0000000..7803e0d --- /dev/null +++ b/geode-docs/docs/geode-native-docs/function-execution/executing-functions.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Executing Functions +--- + +Using the Geode function execution service, you can execute application functions on a single server member, in parallel on a subset of server members, or in parallel on all server members of a distributed system. + +In these procedures, it is assumed that you have defined your client and server regions, and that you have coded and configured your servers to run your functions. In [Function Execution](geodeman/developing/function_exec/chapter_overview.html), see the function execution information for the server side. + +- **[Running the Function](running-function.html)** + + In this section you create an `Execution` object and use its methods to define and run the function. To run a function with high availability, you call `getResult` from the results collector returned from the `execute` method. + +- **[Programming to Get Function Results](handling-function-results.html)** + + Geode provides a default result collector. If you need special results handling, code a custom `ResultsCollector` implementation to replace the provided default. Use the `Execution::withCollector` method to define your custom collector. + +- **[Solutions and Use Cases](solutions-use-cases.html)** + + The function execution service provides solutions for various application use cases. http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/function-execution/function-execution.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/function-execution/function-execution.html.md.erb b/geode-docs/docs/geode-native-docs/function-execution/function-execution.html.md.erb new file mode 100644 index 0000000..a35b3e6 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/function-execution/function-execution.html.md.erb @@ -0,0 +1,22 @@ +--- +title: Function Execution +--- + +*Function Execution* describes how you can execute application functions to achieve linear scalability. It explains how function execution works and lists specific use cases. + +**Note:** +Function execution can be used only along with the pool functionality. For more information about the pool API, see [Using Connection Pools](../connection-pools/connection-pools.html#using-connection-pools). Only C++ versions of Function Execution API interfaces, classes, and methods (like `FunctionService::onRegion`) are shown in text. The code examples show C++ and C\#. + +- **[Understanding Data-Aware Function Routing](data-aware-function-execution.html)** + + Achieving linear scalability is predicated upon being able to horizontally partition the application data such that concurrent operations by distributed applications can be done independently across partitions. + +- **[How Functions Execute](how-functions-execute.html)** + + This section discusses the basic function execution process, how highly available functions execute after a failure, and the execution scenarios for data-dependent and data-independent functions. + +- **[Executing Functions](executing-functions.html)** + + Using the Geode function execution service, you can execute application functions on a single server member, in parallel on a subset of server members, or in parallel on all server members of a distributed system. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/function-execution/handling-function-results.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/function-execution/handling-function-results.html.md.erb b/geode-docs/docs/geode-native-docs/function-execution/handling-function-results.html.md.erb new file mode 100644 index 0000000..8891009 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/function-execution/handling-function-results.html.md.erb @@ -0,0 +1,34 @@ +--- +title: Programming to Get Function Results +--- + +Geode provides a default result collector. If you need special results handling, code a custom `ResultsCollector` implementation to replace the provided default. Use the `Execution::withCollector` method to define your custom collector. + +**Note:** +This section applies only to functions that return results. + +To program your client to get the results from a function, use the result collector returned from the function execution, like this: + +``` pre +ResultCollectorPtr rc = FunctionService::onRegion(region) + ->withArgs(args) + ->withFilter(keySet) + ->withCollector(new MyCustomResultCollector()) + .execute(Function); +CacheableVectorPtr functionResult = rc.getResult(); +``` + +The `getResult` methods of the Geode default result collector block until all results are received, then return the full result set. + +You can handle the results in a custom manner if you wish. To do this: + +1. Write a class that extends `ResultCollector` and code the methods to handle the results as you need. The methods are of two types: one handles data and information from Geode and populates the results set, while the other returns the compiled results to the calling application: + + 1. `addResult` is called by Geode when results arrive from the `Function` methods. Use `addResult` to add a single result to the ResultCollector. + 2. `endResults` is called by Geode to signal the end of all results from the function execution. + 3. `getResult` is available to your executing application (the one that calls `Execution.execute`) to retrieve the results. This may block until all results are available. + 4. `clearResults` is called by Geode to clear partial results from the results collector. This is used only for highly available `onRegion` functions where the calling application waits for the results. If the call fails, before Geode retries the execution, it calls `clearResults` to ready the instance for a clean set of results. + +2. Use the `Execution` object in your executing member to call `withCollector`, passing your custom collector, as shown in the example above. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/function-execution/how-functions-execute.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/function-execution/how-functions-execute.html.md.erb b/geode-docs/docs/geode-native-docs/function-execution/how-functions-execute.html.md.erb new file mode 100644 index 0000000..19435df --- /dev/null +++ b/geode-docs/docs/geode-native-docs/function-execution/how-functions-execute.html.md.erb @@ -0,0 +1,59 @@ +--- +title: How Functions Execute +--- + +This section discusses the basic function execution process, how highly available functions execute after a failure, and the execution scenarios for data-dependent and data-independent functions. + +## How Functions Execute + +1. The calling client application runs the `execute` method on the `Execution` object. The object must already be registered on the servers. +2. The function is invoked on all servers where it needs to run. The locations are determined by the `FunctionService on*` method calls, region configuration, and any filters. +3. If the function has results, the result is returned to the `AddResult` method call in a `ResultCollector` object. +4. The client collects results using the result collector `getResult`. + +## How Highly Available Functions Execute after a Failure + +If a failure occurs in function execution, the error is returned to the calling application. You can code for high availability for `onRegion` functions that return a result, so the function is automatically retried. For information on setting this up on the server side, see [Executing a Function in Apache Geode](geodeman/developing/function_exec/function_execution.html). To use a highly available function, the client must call the results collector `getResult` method. When an execution error occurs or a member crashes while executing, the system does the following: + +1. Waits for all calls to return. +2. Sets a boolean indicating a reexecution is being done. +3. Calls the result collector’s `clearResults` method. +4. Executes the function. + +The system retries the execution up to the number specified in the server pool’s `retryAttempts` setting. If the function continues to fail, the final exception is returned to the `getResult` method. + +## Data-Independent Function Execution + +The figure shows the sequence of events for a data-independent function executed against all available servers. + + + +Figure: Data-Independent Function Invoked from a Client + +Data-Independent Function Invoked on All Servers + +## Data-Dependent Function Execution + +The figure shows a data-dependent function run by a client. The specified region is connected to the server system, so the function automatically goes there to run against all servers holding data for the region. + + + +Figure: Data-Dependent Function Invoked From a Client + +Data-Dependent Function Invoked from a Client + +This shows the same data-dependent function with the added specification of a set of keys on which to run. Servers that don't hold any of the keys are left out of the function execution. + + + +Figure: Data-Dependent Function with Filter Invoked from a Client + +Data-Dependent Function with Filter Invoked From a Client + +This scenario demonstrates the steps in a call to a highly available function. The call fails the first time on one of the participating servers and is successfully run a second time on all servers. + + + +Figure: Highly Available Data-Dependent Function with Failure on First Executions + +Highly Available Data Dependent Function with Failure on First Execution http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/function-execution/running-function.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/function-execution/running-function.html.md.erb b/geode-docs/docs/geode-native-docs/function-execution/running-function.html.md.erb new file mode 100644 index 0000000..fa5e1ce --- /dev/null +++ b/geode-docs/docs/geode-native-docs/function-execution/running-function.html.md.erb @@ -0,0 +1,122 @@ +--- +title: Running the Function +--- + +In this section you create an `Execution` object and use its methods to define and run the function. To run a function with high availability, you call `getResult` from the results collector returned from the `execute` method. + +## Configuring and Running a Function + +You specify the members that run the function and, optionally, the data set over which the functions run. + +- **Servers**. Execute the function in a single server or a set of servers, specified by the server pool. To specify data sets for this type of function, pass arguments in to the function. +- **Data set**. Specify a region and possibly a set of keys on which to run. + +In every client where you want to execute the function and process the results: + +1. Use one of the `FunctionService on*` methods to create an `Execution` object. The `on*` methods, `onRegion`, `onServer` and `onServers`, define the highest level where the function is run. If you use `onRegion` you can further narrow your run scope by setting key filters. The function run using `onRegion` is a data dependent function – the others are data-independent functions. + + You can run a data dependent function against custom partitioned and colocated partitioned regions. From the client, provide the appropriate key sets to the function call. + +2. Use the `Execution` object as needed for additional function configuration. You can: + - Provide a set of data keys to `withFilter` to narrow the execution scope. This works only for `onRegion Execution` objects. + - Provide function arguments to `withArgs`. + - Define a custom `ResultCollector` to `withCollector`. See [Programming to Get Function Results](handling-function-results.html#handling-function-results). + +3. Call the `Execution` object execute method to run the function. +4. To run a function with high availability, call `getResult` from the results collector returned from `execute`. Calling a highly available function without using `getResult` disables the high availability functionality. + +## Running a Function on a Region (C++) + +``` pre +regPtr0 = initRegion(); +ExecutionPtr exc = FunctionService::onRegion(regPtr0); +CacheableVectorPtr routingObj = CacheableVector::create(); +char buf[128]; +bool getResult = true; + +sprintf(buf, "VALUE--%d", 10); +CacheablePtr value(CacheableString::create(buf)); + +sprintf(buf, "KEY--%d", 100); +CacheableKeyPtr key = CacheableKey::create(buf); +regPtr0->put(key, value); + +sprintf(buf, "KEY--%d", 100); +CacheableKeyPtr key1 = CacheableKey::create(buf); +routingObj->push_back(key1); + +CacheablePtr args = routingObj; +CacheableVectorPtr executeFunctionResult = exc->withFilter(routingObj)-> + withArgs(args)->execute(func)->getResult(); +``` + +## Running a Function on a Server Pool (C++) + +``` pre +pptr = PoolManager::find(poolName); +ExecutionPtr exc = FunctionService::onServer(cache); +CacheableVectorPtr routingObj = CacheableVector::create(); +char buf[128]; +bool getResult = true; +sprintf(buf, "VALUE--%d", 10); +CacheablePtr value(CacheableString::create(buf)); + +sprintf(buf, "KEY--%d", 100); +CacheableKeyPtr key = CacheableKey::create(buf); +regPtr0->put(key, value); + +sprintf(buf, "KEY--%d", 100); +CacheableKeyPtr key1 = CacheableKey::create(buf); +routingObj->push_back(key1); + +CacheablePtr args = routingObj; +CacheableVectorPtr executeFunctionResult = +exc->withArgs(args)->execute(func)->getResult(); +``` + +## Running a Function on a Region (C\# .NET) + +``` pre +IRegion fregion = + regionFactory.Create("exampleRegion"); +for (int i = 0; i < 34; i++) +{ + fregion.Put("KEY--" + i, "VALUE--" + i, null); +} + +object[] routingObj = new object[17]; +int j = 0; +for (int i = 0; i < 34; i++) +{ + if (i % 2 == 0) continue; + routingObj[j] = "KEY--" + i; + j++; +} +object args0 = true; +Boolean getResult = true; +// data dependent function execution -- get function with result +Execution exc = + Generic.FunctionService.OnRegion(fregion); +Generic.IResultCollector rc = + exc.WithArgs((IGFSerializable)args0).WithFilter( + (IGFSerializable[])routingObj).Execute(getFuncName); +object[] executeFunctionResult = rc.GetResult(); +``` + +## Running a Function on a Server Pool (C\# .NET) + +``` pre +exc = Generic.FunctionService.OnServer(cache); +List args1 = new List(); +for (int i = 0; i < routingObj.Length; i++) +{ + Console.WriteLine("routingObj[{0}]={1}.", i, (routingObj[i] as string)); + args1.Add(routingObj[i]); +} +rc = exc.WithArgs((IGFSerializable)args1).Execute(getFuncIName); +executeFunctionResult = rc.GetResult(); +Console.WriteLine("on one server: result count= {0}.", + executeFunctionResult.Length); +``` + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/function-execution/solutions-use-cases.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/function-execution/solutions-use-cases.html.md.erb b/geode-docs/docs/geode-native-docs/function-execution/solutions-use-cases.html.md.erb new file mode 100644 index 0000000..364d53d --- /dev/null +++ b/geode-docs/docs/geode-native-docs/function-execution/solutions-use-cases.html.md.erb @@ -0,0 +1,13 @@ +--- +title: Solutions and Use Cases +--- + +The function execution service provides solutions for various application use cases. + +- An application that executes a server-side transaction or makes data updates using the Geode distributed locking service. +- An application that initializes some of its components once on each server, which might be used later by executed functions. +- Initialization and startup of a third-party service, such as a messaging service. +- Any arbitrary aggregation operation that requires iteration over local data sets that can be done more efficiently through a single call to the cache server. +- Any kind of external resource provisioning that can be done by executing a function on a server. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/getting_started/system_requirements/gemfire_native_client_requirements.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/getting_started/system_requirements/gemfire_native_client_requirements.html.md.erb b/geode-docs/docs/geode-native-docs/getting_started/system_requirements/gemfire_native_client_requirements.html.md.erb new file mode 100644 index 0000000..f3fb7c9 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/getting_started/system_requirements/gemfire_native_client_requirements.html.md.erb @@ -0,0 +1,190 @@ +--- +title: GemFire Native Client Supported Configurations +--- + +The Pivotal GemFire native client provides access for C++ and Microsoft® .NET™ clients to the GemFire distributed system. It operates on platforms running Microsoft Windows, Linux (Intel), and Sun Solaris. + +Native Client version 9.0 works with Pivotal GemFire versions 8.2.1 and later. + +Operating system requirements are listed in the chart below: + + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Operating SystemProcessor and ArchitectureRAMSwap Space64-Bit Disk Space Required
Solaris 11x86-64 +2GB256MB90MB
RHEL 6 (deprecated)x86-642GB256MB120MB
RHEL 7x86-642GB256MB120MB
SLES 11** (deprecated)x86-642GB256MB120MB
SLES 12**x86-642GB256MB120MB
Windows 2012 Server R2x86-642GB256MB125MB
Windows 8.1 (deprecated)x86-642GB256MB125MB
Windows 10x86-642GB256MB125MB
+ + + +\*\*Indicates operating systems that have not been fully tested but are still supported. + +## Host Machine Requirements + +Each machine that runs a native client must meet the following requirements: + +- A system clock set to the correct time and a time synchronization +service such as Network Time Protocol (NTP). +Correct time stamps permit the following activities: + - Logs that are useful for troubleshooting. Synchronized time stamps ensure that log messages from different hosts can be merged to reproduce an accurate chronological history of a distributed run. + - Aggregate product-level and application-level time statistics. + - Accurate monitoring of the system with scripts and other tools that read the system statistics and log files. +- The host name and host files are properly configured for the machine. +- Many default Linux installations use SYN cookies to protect the +system against malicious attacks that flood TCP SYN packets. +The use of SYN cookies dramatically reduces network bandwidth, +and can be triggered by a running GemFire distributed system. + + To disable SYN cookies permanently: + 1. Edit the `/etc/sysctl.conf` file to include the following line: + + ``` pre + net.ipv4.tcp_syncookies = 0 + ``` + Setting this value to zero disables SYN cookies. + 2. Reload `sysctl.conf`: + + ``` pre + sysctl -p + ``` + +## Windows Support Details + +**Runtime Library Requirements** + +The GemFire native client also requires the Microsoft Visual C++ 2013 Redistributable Package. This package is installed for you when you use the native client .msi installer. If you do not use the .msi installer, you will need to install this package for your platform architecture manually ([x86-64](https://www.microsoft.com/en-us/download/details.aspx?id=40784)) on all machines that will run the GemFire native client. This package contains runtime libraries needed by the native client. + +**.NET Framework Version Support** + +The Pivotal GemFire native client is supported with Microsoft .NET Framework 4.5.2. + +A Microsoft .NET Framework must be installed to support the C++/CLI (Common Language Infrastructure) library for the native client. + +The Pivotal GemFire native client 9.0 supports .NET 4.5.2 and Visual Studio 2013 (for compiling C++ applications on Windows). For more information on the features of .NET and Visual Studio Community Edition 2013 Update 5, see [https://msdn.microsoft.com/en-us/library/dd831853(v=vs.120).aspx](https://msdn.microsoft.com/en-us/library/dd831853(v=vs.120).aspx) . + +## Linux + +The following table lists the RPM package dependencies for the Linux distribution. The i386 or i686 after the package name indicates that you must install the package for that particular architecture regardless of the native operating system architecture. All of the packages listed are available with the default media for the distribution. + + + +| Linux Version | glibc | libgcc | +|-----------------------------------------------------|--------------|---------------| +| Red Hat Enterprise Linux Server release 7 (x86-64) | glibc (i686) | libgcc (i386) | + + +For versions of Linux not listed in the table, you can verify that you meet the native client dependencies at the library level by using the `ldd` tool and entering this command: + +``` pre +prompt> ldd $GFCPP/lib/libgfcppcache.so +``` + +This step assumes you have already installed the native client and have set the GFCPP environment variable to *productDir*, where *productDir* represents the location of the NativeClient\_*xxxx*\_b*nnnnn* directory (*xxxx* is the four-digit product version and b*nnnnn* is the product build number). + +The following libraries are external dependencies of the native library, `libgfcppcache.so`. Verify that the ldd tool output includes all of these: + +- libdl.so.2 +- libm.so.6 +- libpthread.so.0 +- libc.so.6 +- libz.so.1 + + +## Running Pivotal GemFire Native Client on vSphere + +Without tuning, the Pivotal GemFire native client can suffer a performance drop in virtual environments, including the VMware vSphere virtual platform. Without correct tuning, you can expect to see significant performance degradation when running the GemFire native client on vSphere versus running GemFire on dedicated hardware. + +We recommend that you tune your GemFire native client on vSphere deployments using the same guidelines published for Pivotal GemFire. + +See [Improving GemFire Performance on vSphere](geodeman/managing/monitor_tune/gemfire_performance_on_vsphere.html) for a list of guidelines and recommendations. + +## Software Requirements for Using SSL + +If you plan on using SSL in your GemFire native client and server deployment, you will need to download and install OpenSSL. + +The GemFire native client requires OpenSSL 1.0.1t or later. For Windows platforms, you can use either the regular or the OpenSSL "Light" version. + +In addition, make sure that your system environment variables have been configured to include OpenSSL. + +See [SSL Client/Server Communication](../../security/overviewsslclientserver.html#security) for instructions. http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/gfcpp.properties/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/gfcpp.properties/chapter_overview.html.md.erb b/geode-docs/docs/geode-native-docs/gfcpp.properties/chapter_overview.html.md.erb new file mode 100644 index 0000000..a242adb --- /dev/null +++ b/geode-docs/docs/geode-native-docs/gfcpp.properties/chapter_overview.html.md.erb @@ -0,0 +1,17 @@ +--- +title: gfcpp.properties Example File +--- + +Use the gfcpp.properties file to configure distributed system connections for the Apache Geode native client. + +The following example shows the format of a gfcpp.properties file. The first two attributes in this example should be set by programmers during application development, while other attributes are set on-site during system integration. The properties and their default settings that can be set in this file are described in detail in [Attributes in gfcpp.properties](../setting-properties/attributes-gfcpp.html#attributes-gfcpp). + +## gfcpp.properties File Format + +``` pre +#Tue Feb 14 17:24:02 PDT 2006 +log-level=info +cache-xml-file=./cache.xml +stacktrace-enabled=true +``` + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/gfcpp.properties/default_sample_file.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/gfcpp.properties/default_sample_file.html.md.erb b/geode-docs/docs/geode-native-docs/gfcpp.properties/default_sample_file.html.md.erb new file mode 100644 index 0000000..4ebf65f --- /dev/null +++ b/geode-docs/docs/geode-native-docs/gfcpp.properties/default_sample_file.html.md.erb @@ -0,0 +1,104 @@ +--- +title: Using the Default Sample File +--- + +A sample gfcpp.properties file is included with the Apache Geode native client installation in the _product-dir_/defaultSystem directory. + +To use this file: + +1. Copy the file to the directory where you start the application. +2. Uncomment the lines you need and edit the settings as shown in this example: + + ``` pre + cache-xml-file=test.xml + ``` + +3. Start the application. + +## Default gfcpp.properties File + +``` pre +# Default C++ distributed system properties +# Copy to current directory and uncomment to override defaults. +# +## Debugging support, enables stacktraces in gemfire::Exception. +# +# The default is false, uncomment to enable stacktraces in exceptions. +#stacktrace-enabled=true +#crash-dump-enabled=true +# +# +## Cache region configurtion +# +#cache-xml-file=cache.xml +# +## Log file config +# +#log-file=gemfire_cpp.log +#log-level=config +# zero indicates use no limit. +#log-file-size-limit=0 +# zero indicates use no limit. +#log-disk-space-limit=0 +# +## Statistics values +# +# the rate is in seconds. +#statistic-sample-rate=1 +#statistic-sampling-enabled=true +#statistic-archive-file=statArchive.gfs +# zero indicates use no limit. +#archive-file-size-limit=0 +# zero indicates use no limit. +#archive-disk-space-limit=0 +#enable-time-statistics=false +# +## Heap based eviction configuration +# +# maximum amount of memory used by the cache for all regions, 0 disables this feature +#heap-lru-limit=0 +# percentage over heap-lru-limit when LRU will be called. +#heap-lru-delta=10 +# +## Durable client support +# +#durable-client-id= +#durable-timeout=300 +# +## SSL socket support +# +#ssl-enabled=false +#ssl-keystore= +#ssl-truststore= +# +## .NET AppDomain support +# +#appdomain-enabled=false +# +## Misc +# +#conflate-events=server +#disable-shuffling-of-endpoints=false +#grid-client=false +#max-fe-threads= +#max-socket-buffer-size=66560 +# the units are in seconds. +#connect-timeout=59 +#notify-ack-interval=10 +#notify-dupcheck-life=300 +#ping-interval=10 +#redundancy-monitor-interval=10 +#auto-ready-for-events=true +# +## module name of the initializer pointing to sample +## implementation from templates/security +#security-client-auth-library=securityImpl +## static method name of the library mentioned above +#security-client-auth-factory=createUserPasswordAuthInitInstance +## credential for Dummy Authenticator configured in server. +## note: security-password property will be inserted by the initializer +## mentioned in the above property. +#security-username=root +``` + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/gfcpp.properties/gfcpp.properties_search_path.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/gfcpp.properties/gfcpp.properties_search_path.html.md.erb b/geode-docs/docs/geode-native-docs/gfcpp.properties/gfcpp.properties_search_path.html.md.erb new file mode 100644 index 0000000..ff849e5 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/gfcpp.properties/gfcpp.properties_search_path.html.md.erb @@ -0,0 +1,11 @@ +--- +title: Search Path for Multiple gfcpp.properties Files +--- + +The native client and cache server processes first look for their properties file in the _product-dir_/defaultSystem directory, then in the working directory. + +Any properties set in the working directory override settings in the `defaultSystem/gfcpp.properties` file. + +If you are running multiple processes on one machine, you can configure the `gfcpp.properties` file in the `defaultSystem` directory as a shared file that all processes can find. If a few processes need a slightly different configuration, you can put individual `gfcpp.properties` files in their home directories to override specific properties. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/gfcpp.properties/overriding_gfcpp.properties.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/gfcpp.properties/overriding_gfcpp.properties.html.md.erb b/geode-docs/docs/geode-native-docs/gfcpp.properties/overriding_gfcpp.properties.html.md.erb new file mode 100644 index 0000000..3303cdb --- /dev/null +++ b/geode-docs/docs/geode-native-docs/gfcpp.properties/overriding_gfcpp.properties.html.md.erb @@ -0,0 +1,9 @@ +--- +title: Overriding gfcpp.properties Settings +--- + +Application developers have the option of configuring system attributes programmatically, rather than using the `gfcpp.properties` file. + +Attributes set programmatically override any matching attribute settings in the `gfcpp.properties` file, but additional attributes not set programmatically will be configured using the settings in `gfcpp.properties`. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/glossary.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/glossary.html.md.erb b/geode-docs/docs/geode-native-docs/glossary.html.md.erb new file mode 100644 index 0000000..3e860ef --- /dev/null +++ b/geode-docs/docs/geode-native-docs/glossary.html.md.erb @@ -0,0 +1,213 @@ +--- +title: Glossary +--- + +This glossary defines terms used in the documentation. + +## API + +Application Programming Interface. Geode provides APIs to cached data for C++ and .NET applications. + +## application program + +A program designed to perform a specific function directly for the user or, in some cases, for another application program. Geode applications use the Geode application programming interfaces (APIs) to modify cached data. + +## cache + +A cache created by an application or cache server process. For the process, its cache is the point of access to all caching features and the only view of the cache that is available. Cache creation requires membership in the distributed system. See also [local cache](#nc_glossary_local_cache) and [remote cache](#nc_glossary_remote_cache). + +## cache configuration file + +An XML file that declares the initial configuration of a cache, commonly named `cache.xml`. C++ and .NET applications can configure the cache additionally through the Geode programming APIs. + +## cache listener + +User-implemented plug-in for receiving and handling region entry events. A region's cache listener is called after an entry in the local cache is modified. + +## cache loader + +User-implemented plug-in for loading data into a region. A region's cache loader is used to load data that is requested of the region but is not available in the distributed system. For a distributed region, the loader that is used can be in a different cache from the one where the data-request operation originated. See also [cache writer](#nc_glossary_cache_writer) and [netSearch](#nc_glossary_netSearch). + +## cache server + +A long-running, configurable caching process, generally used to serve cached data to the applications. Usually, cache servers are configured to operate as servers in a client-server typology and their regions are configured to be replicates. See also [server](#nc_glossary_server). + +## cache writer + +User-implemented plug-in intended for synchronizing the cache with an outside data source. A region's cache writer is a synchronous listener to cache data events. The cache writer has the ability to abort a data modification. See also [cache loader](#nc_glossary_cache_loader). + +## caching enabled + +Specifies whether data is cached in the region. Geode gives you the option of running applications without entry caching. For example, you can configure a distributed system as a simple messaging service. + +## client + +In a client-server topology, clients can connect to cache servers, create new regions on the cache server, and store data in the cache server region. Clients can also connect to existing regions on a cache server and do directed gets and puts on the cache server. Clients do not track membership information about other clients, nor do they share information with other clients. + +## concurrency level + +An estimate of the number of threads expected to concurrently modify values in the region. The actual concurrency may vary; this value is used to optimize the allocation of system resources. + +## connection + +What an application uses to access a Geode distributed system. An application can connect to a Geode system by calling the `DistributedSystem::connect` function with the appropriate parameter settings. An application must connect to a distributed system to gain access to Geode functionality. + +## destroy + +Remove an entry from a region or remove a region from a cache. + +## disk policy + +Determines whether LRU entries exceeding the entries limit for a caching region are destroyed or written to disk. + +## distributed scope + +Enables a region to automatically send entry value updates to remote caches and incorporate updates received from remote caches. The scope identifies whether distribution operations must wait for acknowledgement from other caches before continuing. A distributed region's **cache loader** and **cache writer** (defined in the local cache) can be invoked for operations originating in remote caches. + +## distributed system + +One or more Geode system members that have been configured to communicate with each other, forming a single, logical system. Also used for the object that is instantiated to create the connection between the distributed system members. + +## DTD + +Document Type Definition. A language that describes the contents of a Standard Generalized Markup Language (SGML) document. The DTD is also used with XML. The DTD definitions can be embedded within an XML document or in a separate file. + +## entry + +A data object in a region. A region entry consists of a key and a value. The value is either null (invalid) or an object. A region entry knows what region it is in. See also [region data](#nc_glossary_region_data), [entry key](#nc_glossary_entry_key), and [entry value](#nc_glosssary_entry_value). + +## entry key + +The unique identifier for an entry in a region. + +## entry value + +The data contained in an entry. + +## expiration + +A cached object expires when its time-to-live or idle timeout counters are exhausted. A region has one set of expiration attributes for itself and one set for all region entries. + +## expiration action + +The action to be taken when a cached object expires. The expiration action specifies whether the object is to be invalidated or destroyed, and whether the action is to be performed only in the local cache or throughout the distributed system. A destroyed object is completely removed from the cache. A region is invalidated by invalidating all entries contained in the region. An entry is invalidated by having its value marked as invalid. + +Expiration attributes are set at the region level for the region and at the entry level for entries. See also [idle timeout](#nc_glossary_idle_timeout) and [time-to-live](#nc_glossary_time-to-live). + +## factory method + +An interface for creating an object which at creation time can let its subclasses decide which class to instantiate. The factory method helps instantiate the appropriate subclass by creating the correct object from a group of related classes. + +## idle timeout + +The amount of time a region or region entry may remain in the cache unaccessed before being expired. Access to an entry includes any `get` operation and any operation that resets the entry's time-to-live counter. Region access includes any operation that resets an entry idle timeout, and any operation that resets the region's time-to-live. + +Idle timeout attributes are set at the region level for the region and at the entry level for entries. See also [time-to-live](#nc_glossary_time-to-live) and [expiration action](#nc_glossary_expiration_action). + +## interest list + +A mechanism that allows a region to maintain information about receivers for a particular key-value pair in the region, and send out updates only to those nodes. Interest lists are particularly useful when you expect a large number of updates on a key as part of the entry life cycle. + +## invalid + +The state of an object when the cache holding it does not have the current value of the object. + +## invalidate + +Remove only the value of an entry in a cache, not the entry itself. + +## listener + +An event handler. The listener registers its interest in one or more events and is notified when the events occur. + +## load factor + +A region attribute that sets initial parameters on the underlying hashmap used for storing region entries. + +## local cache + +The part of the distributed cache that is resident in the current process. This term is used to differentiate the cache where a specific operation is being performed from other caches in the distributed system. See also [remote cache](#nc_glossary_remote_cache). + +## local scope + +Enables a region to hold a private data set that is not visible to other caches. See also [scope](#nc_glossary_scope). + +## LRU + +Least Recently Used. Refers to a region entry or entries most eligible for eviction due to lack of interest by client applications. + +## LRU entries limit + +A region attribute that sets the maximum number of entries to hold in a caching region. When the capacity of the caching region is exceeded, LRU is used to evict entries. + +## membership + +Applications and cache servers connect to a Geode distributed system by invoking the static function `DistributedSystem::connect`. Through this connection, the application gains access to the APIs for distributed data caches. When a C++ or .NET application connects to a distributed system, it specifies the system it is connecting to by indicating the communication protocol and address to use to find other system members. + +## netSearch + +The method used by Geode to search remote caches for a data entry that is not found in the local cache region. This operates only on distributed regions. + +## overflows + +An eviction option that causes the values of LRU entries to be moved to disk when the region reaches capacity. See [disk policy](#nc_glossary_disk_policy). + +## persistence manager + +The persistence manager manages the memory-to-disk and disk-to-memory actions for LRU entries. See [overflows](#nc_glossary_overflows). + +## region + +A logical grouping of data within a cache. Regions are used to store data entries (see [entry](#nc_glossary_entry)). Each region has a set of attributes governing activities such as expiration, distribution, data loading, events, and eviction control. + +## region attributes + +The class of attributes governing the creation, location, distribution, and management of a region and its entries. + +## region data + +All of the entries directly contained in the region. + +## region entry + +See [entry](#nc_glossary_entry). + +## remote cache + +Any part of the distributed cache that is resident in a process other than the current one. If an application or cache server does not have a data entry in the region in its local cache, it can do a `netSearch` in an attempt to retrieve the entry from the region in a remote cache. See also [local cache](#nc_glossary_local_cache). + +## scope + +Region attribute. Identifies whether a region keeps its entries private or automatically sends entry value updates to remote caches and incorporates updates received from remote caches. The scope also identifies whether distribution operations must wait for acknowledgement from other caches before continuing. See also [distributed scope](#nc_glossary_distributed_scope) and [local scope](#nc_glossary_local_scope). + +## serialization + +The process of converting an object graph to a stream of bytes. + +## server + +In a client-server topology, the server manages membership and allows remote operations. The server maintains membership information for its clients in the distributed system, along with information about peer applications and other servers in the system. See also **cache server**. + +## system member + +A process that has established a connection to a distributed system. + +## time-to-live + +The amount of time a region or region entry may remain in the cache without being modified before being expired. Entry modification includes creation, update, and removal. Region modification includes creation, update, or removal of the region or any of its entries. + +Time-to-live attributes are set at the region level for the region, and at the entry level for entries. See also **idle timeout** and **expiration action**. + +## XML + +EXtensible Markup Language. An open standard for describing data from the W3C, XML is a markup language similar to HTML. Both are designed to describe and transform data, but where HTML uses predefined tags, XML allows tags to be defined inside the XML document itself. Using XML, virtually any data item can be identified. The XML programmer creates and implements data-appropriate tags whose syntax is defined in a DTD file or an XSD (XML schema definition.) + +## XML schema definition + +The definition of the structure, content, and semantics used in an XML document. The definition can be used to verify that each item of content in a document adheres to the specification of the element in which the content is placed. The XML schema is a superset of DTD. Unlike DTD, XML schemas are written in XML syntax, which, although more verbose than DTD, are more descriptive and can have stronger typing. Files containing XML schema definitions generally have the XSD extension. + +## XSD + +See XML schema definition. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/images/SQLite_Persistence_Mgr.png ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/images/SQLite_Persistence_Mgr.png b/geode-docs/docs/geode-native-docs/images/SQLite_Persistence_Mgr.png new file mode 100644 index 0000000..0384874 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/images/SQLite_Persistence_Mgr.png differ http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/developing-linux.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/developing-linux.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/developing-linux.html.md.erb new file mode 100644 index 0000000..a2072ed --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/developing-linux.html.md.erb @@ -0,0 +1,86 @@ +--- +title: Developing C++ Programs on Linux +--- + +This section describes how to build and run a native client application on Linux. + +**Note:** When compiling external projects or applications that are used or referenced by the Geode native client, make sure that you compile them for the same target architecture as your native client installation. For example, if you installed the 64-bit (x86) version of the native client, compile your external projects for 64-bit (x86) architecture. + +## Step 1. Set Environment Variables + +Set the native client environment variables on each Linux host. For each case, *product-dir* is the path to the native client product directory. + +**For Bourne and Korn shells (sh, ksh, bash)** + + +GFCPP=_product-dir_;export GFCPP
+PATH=$GFCPP/bin:$PATH;export PATH
+LD\_LIBRARY\_PATH=$GFCPP/lib:$LD\_LIBRARY\_PATH;export LD\_LIBRARY\_PATH + + +## Step 2. Compile C++ Clients and Dynamically Link Them to the GemFire Library + +On Linux, the `g++` compiler is supported. To build and link a C++ client to GemFire on Linux, the compilation command line must include the arguments listed in the following table. + + + +| Argument | Explanation | +|--------------------|----------------------------------------------------------| +| `-D_REENTRANT` | Required to compile Linux programs in a thread-safe way. | +| `-m32` or `-m64` | Enables 32-bit or 64-bit compilation. | +| `-I$GFCPP/include` | Specifies the native client `include` directory. | + + +The following table lists the linker switches that must be present on the command line when dynamically linking to the GemFire library. + + + +| Argument | Explanation | +|---------------------|----------------------------------------------------------------------------------------------------| +| `-rpath $GFCPP/lib` | Tells the linker to look in `$GFCPP/lib` for libraries on which the native client library depends. | +| `-L$GFCPP/lib` | Tells the linker where to find the named libraries. | +| `-o durableclient` | Tells the linker to output an object file named 'durableclient'. | +| `-lgfcppcache` | Links the native client C++ cache library to the compiled executable. | + + +The following examples compile and link the `$GFCPP/SampleCode/quickstart/cpp/DurableClient.cpp` client to the `durableclient` output file. + +**Compiling and Dynamically Linking on Linux for 32-bit** + +``` pre +g++ \ +-D_REENTRANT \ +-03 \ +-Wall \ +-m32 \ +-I$GFCPP/include \ +cpp/DurableClient.cpp \ +cpp/plugins/DurableCacheListener.cpp \ +-o cpp/DurableClient \ +-L$GFCPP/lib \ +-Wl,-rpath,$GFCPP/lib \ +-lgfcppcache +``` + +**Compiling and Dynamically Linking on Linux for 64-bit** + +``` pre +g++ \ +-D_REENTRANT \ +-03 \ +-Wall \ +-m64 \ +-I$GFCPP/include \ +cpp/DurableClient.cpp \ +cpp/plugins/DurableCacheListener.cpp \ +-o cpp/DurableClient \ +-L$GFCPP/lib \ +-Wl,-rpath,$GFCPP/lib \ +-lgfcppcache +``` + +## Step 3. Make Sure the Native Client Library Can Be Loaded + +When the C++ application is dynamically linked to the native client library, the library must be dynamically loadable. + +To ensure that the native client library is available for loading, make sure you have added the path *product-dir*`/lib` to the LD\_LIBRARY\_PATH environment variable, where *product-dir* is the path to the Geode product directory. http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/developing-solaris.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/developing-solaris.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/developing-solaris.html.md.erb new file mode 100644 index 0000000..d05a216 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/developing-solaris.html.md.erb @@ -0,0 +1,44 @@ +--- +title: Developing C++ Programs on Solaris +--- + +This section describes how to build and run a native client application on Solaris. + +## Step 1. Set Environment Variables + +**Note:** When compiling external projects or applications that are used or referenced by the native client, make sure that you compile them for the same target architecture as your native client installation. For example, if you installed the 32-bit (x86) version of the native client, compile your external projects for 32-bit (x86) architecture. + +Set the native client environment variables on each Solaris host. For each case, *product-dir* is the path to the native client product directory. + +**For Bourne and Korn shells (sh, ksh, bash)** + + +GFCPP=_product-dir_; export GFCPP
+PATH=$GFCPP/bin:$PATH;export PATH
+LD\_LIBRARY\_PATH=$GFCPP/lib:$LD\_LIBRARY\_PATH;export LD\_LIBRARY\_PATH + + +## Step 2. Compile C++ Clients and Dynamically Link to Them to Native Client Library + +Version 5.9 of the *SUNpro* compiler is supported on Solaris. The linker switches vary according to whether you are statically linking to the native client library. + +To build and link a C++ client on Solaris, the compilation command line must include the appropriate arguments from this table. + + + +| Argument | Explanation | +|------------------------------------------------------------------------------------------------|------------------------------------------------------------| +| `-D_REENTRANT` | Required to compile Solaris programs in a thread-safe way. | +| `-xarch=v8plus` | Enables 32-bit compilation. | +| `-xarch=v9` | Enables 64-bit compilation. | +| `-ldl`; `-lpthread`; `-lc`; `-lm`; `-lsocket`; `-lrt`; `-lnsl`; `-ldemangle`; `-lkstat`; `-lz` | Additional libraries. | +| `-library=stlport4` | Solaris library compilation. | +| `-I$ GFCPP /include` | Specifies the GemFire include directory. | + + + +## Step 3. Make Sure the Native Client Library Can Be Loaded + +When a C++ application is not statically linked to the native client library, the library must be dynamically loadable. + +To verify that the native client library is available for loading, make sure you have added the path *product-dir*`/lib` to the LD\_LIBRARY\_PATH environment variable, where *product-dir* is the path to the Geode product directory. http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/developing-windows.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/developing-windows.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/developing-windows.html.md.erb new file mode 100644 index 0000000..d66b9c0 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/developing-windows.html.md.erb @@ -0,0 +1,56 @@ +--- +title: Developing C++ Programs on Windows +--- + +Geode uses the Visual Studio 2010 Service Pack 1 compiler for C++ programs on Windows, which invokes Microsoft® `cl.exe` from the command line at compile time. + +The Geode native client supports .NET 4.0 and Visual Studio 2010. For advantages and more information on the features of .NET 4.0 and Visual Studio 2010 SP1, see [http://msdn.microsoft.com/en-us/library/dd831853(v=vs.100).aspx](http://msdn.microsoft.com/en-us/library/dd831853(v=vs.100).aspx) and [http://msdn.microsoft.com/en-us/library/vstudio/w0x726c2(v=vs.100).aspx](http://msdn.microsoft.com/en-us/library/vstudio/w0x726c2(v=vs.100).aspx). + +Visual Studio 2010 SP1 is the recommended compiler. If you are using any other compiler, contact technical support for assistance. + +**Note:** When compiling external projects or applications that are used or referenced by the native client, make sure that you compile them for the same target architecture as your native client installation. For example, if you installed the 32-bit (x86) version of the native client, compile your external projects for 32-bit (x86) architecture. + +## Step 1. Installer Sets Up Environment Variables + +When you install on Windows, the installer performs these tasks: + +- Sets the *GFCPP* environment variable to *product-dir*, where *product-dir* is the path to the native client product directory. +- Adds the *%GFCPP%\\bin* executable directory to the Windows PATH environment variable. + +## Step 2. Choose 32-bit or 64-bit Command-line Prompt + +For 32-bit: + +Start > Programs > Microsoft Visual Studio > 2010 > Visual Studio Tools > Visual Studio 2010 Command Prompt + +For 64-bit: + +Start > Programs > Microsoft Visual Studio 2010 > Visual Studio Tools > Visual Studio 2010 x64 Win64 Command Prompt + +To build using the Microsoft Visual Studio Interface, from the Solutions Platform, choose **Win32** or **x86** from the Build menu for 32-bit builds or x64 for a 64-bit build. + +## Step 3. Compile C++ Clients and Dynamically Link Them to Native Client Library + +The following table lists the compiler and linker switches that must be present on the `cl.exe` command line. + +**Note:** +If you want to use the Visual Studio user interface instead of invoking `cl.exe` from the command line, be sure to supply these parameters. + + + +| Argument | Explanation | +|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------| +| `/MD` | Memory model. | +| `/EHsc` | Catches C++ exceptions only and tells the compiler to assume that \*extern\* C functions never throw a C++ exception. | +| `/GR` | Runtime type information. | +| `-I%GFCPP%\include` | Specifies the Geode `include` directory. | +| `%GFCPP%\lib\gfcppcache.lib` | Specifies the library file for the shared library. | +| `/D_CRT_SECURE_NO_DEPRECATE` | Suppresses warnings. Required for Visual Studio 2010. | +| `/D_CRT_NON_CONFORMING_SWPRINTFS` | Suppresses warnings. Required for Visual Studio 2010. | + + +## Step 4. Verify that You Can Load the Native Client Library + +Because Geode does not provide a library that can be linked statically into an application on Windows, you must dynamically link to the native client library. + +To make the native client library available for loading, verify that the directory _product-dir_/bin is included in the PATH environment variable, where *product-dir* is the path to the Geode product directory. http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/examples-quickstart.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/examples-quickstart.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/examples-quickstart.html.md.erb new file mode 100644 index 0000000..3708859 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/examples-quickstart.html.md.erb @@ -0,0 +1,15 @@ +--- +title: QuickStart Examples and Guide +--- + +Run the native client QuickStart examples and read the QuickStart Guide to understand native client functionality. + +- **[Running the QuickStart Examples](../../nativeclient/introduction/product-examples.html)** + + The QuickStart examples demonstrate the capabilities of the native client, and they provide source code so you can examine how each example is designed. C++ and C\# examples demonstrate how the native client performs as a C++ or C\# client. + +- **[Accessing the QuickStart Guide](../../nativeclient/introduction/quickstart.html)** + + The QuickStart Guide for the native client consists of a set of compact programming samples that demonstrate both C++ and C\# client operations. + + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/install-overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/install-overview.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/install-overview.html.md.erb new file mode 100644 index 0000000..1cc80aa --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/install-overview.html.md.erb @@ -0,0 +1,17 @@ +--- +title: Installing the Native Client +--- + +Installing and uninstalling the native client varies based on operating system. + +- **[Installing on Linux or Solaris](install-unix.html)** + + Install the native client on Linux or Solaris by extracting the contents of a ZIP file, and setting up the environment. + +- **[Installing on Windows](install-windows.html)** + + Install the native client by using the Windows installer GUI interface or the command line. + +- **[Uninstalling the Native Client](uninstall.html)** + + Uninstalling the native client varies based on operating system. http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/install-unix.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/install-unix.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/install-unix.html.md.erb new file mode 100644 index 0000000..41cc295 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/install-unix.html.md.erb @@ -0,0 +1,33 @@ +--- +title: Installing on Linux or Solaris +--- + +Install the native client on Linux or Solaris by extracting the contents of a ZIP file, and setting up the environment. + +## Installation Prerequisites + +Before installing the GemFire native client, complete the following prerequisites: + +- Confirm that your system meets the hardware and software requirements described in [GemFire Native Client Supported Configurations](../getting_started/system_requirements/gemfire_native_client_requirements.html#concept_7AE0C1CB11244095A50CCB52A09A09A1). +- From the [Pivotal GemFire download page](https://network.pivotal.io/products/pivotal-gemfire), select **Download**. +- Under File Groups, select and download the Pivotal GemFire native client ZIP file appropriate for your operating system and processor architecture. + - For Linux platforms, download `pivotal-gemfire-nativeclient-linux-64bit-XXX.zip`. `XXX` represents the version number of the product, for example `9.0.0`. + - For Solaris platforms, download `pivotal-gemfire-nativeclient-Solaris-ARCHITECTURE-64bit-XXX.zip`. `ARCHITECTURE` will be `sparc` or `x86`, matching your platform's processor. `XXX` represents the version number of the product, for example `9.0.0`. + +## Uncompress the ZIP File + +Uncompress the ZIP file. For example: + +```pre +unzip pivotal-gemfire-nativeclient-linux-64bit-9.0.0.zip +``` +The directory created is the *product-dir* used in setting environment variables. + +## Environment Variables + +Set the environment: + +- Set the `GFCPP` environment variable to *product-dir*. +- Add `$GFCPP/bin` to the `PATH`. +- Add `$GFCPP/lib` to the `LD_LIBRARY_PATH`. + http://git-wip-us.apache.org/repos/asf/geode-native/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/install-windows.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/install-windows.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/install-windows.html.md.erb new file mode 100644 index 0000000..69a6316 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/install-windows.html.md.erb @@ -0,0 +1,60 @@ +--- +title: Installing on Windows +--- + +Install the native client by using the Windows installer GUI interface or the command line. + +## Prerequisites + +Before installing the GemFire native client, complete the following prerequisites: + +- Confirm that your system meets the hardware and software requirements described in [Windows Support Details](../getting_started/system_requirements/gemfire_native_client_requirements.html#concept_7AE0C1CB11244095A50CCB52A09A09A1__section_3A8A0684D68E467EBA498D939E91C5AA). +- From the [Pivotal GemFire download page](https://network.pivotal.io/products/pivotal-gemfire), select **Download**. +- On the Pivotal GemFire product download page, select and download the Pivotal GemFire native client MSI appropriate for your hardware architecture. + +**Note:** +If you do not install the native client using the MSI installer or the msiexec command-line, then you will need to manually perform the configuration steps, such as configure your `GFCPP` and `PATH` environment variables, and install the Microsoft Visual C++ 2013 Redistributable Package. + +## Install with the Windows Installer + +The native client can be installed on Windows by using the `pivotal-gemfire-nativeclient-64bit-XXX.msi` Windows installer. `XXX` represents the version of the product, for example `9.0.0`. The installer requires `msiexec` version 3.0 or higher. + +While logged in with administrative privileges, +double-click the MSI file to start the installation. +Enter the installation location of the native client when prompted. + +The MSI installer installs the Microsoft Visual C++ 2013 Redistributable Package for your platform architecture ([https://www.microsoft.com/en-us/download/details.aspx?id=40784](https://www.microsoft.com/en-us/download/details.aspx?id=40784)). This package contains runtime libraries required by the native client. + +The MSI installer automatically configures these native client system environment settings: + +- Sets the `GFCPP` environment variable to *product-dir*, where *product-dir* represents the installation location chosen. +- Adds `%GFCPP%\bin` to the Windows `PATH`. + +## Install from the MSI Command Line + +To use the command line for installation, substitute an appropriate value for `XXX` in a command with syntax: + +``` pre +msiexec /q /i pivotal-gemfire-nativeclient-64bit-XXX.msi ^ +DEFAULT_INSTALLDIR= +``` + +The following table lists common `msiexec` command-line options, along with an explanation of their usage. For a list of all command-line options, enter `msiexec/?`. + + + +| Option | Explanation | +|-----------------------------|---------------------------------------------------------------------| +| `/q` | Creates a quiet installation with no interface or prompts. | +| `/i` | Indicates that the product is to be installed or configured. | +| `DEFAULT_INSTALLDIR=` | Specifies the destination directory, if different from the default. | +| `/x` | Indicates a product uninstall procedure. | + +## Repair a Windows Installation + +If problems occur with your Windows native client installation you can initiate a repair operation to restore any missing elements or registry settings. + +1. Double-click the MSI file, then click Next in the Setup Wizard screen. +2. In the following screen, click the Repair button. +3. In the next screen, click the Repair button. +