Note: Documentation for Pivotal GemFire 7.0.x is now available at http://docs.gopivotal.com/gemfire/index.html. Please reference the docs.gopivotal.com site for the latest and most up-to-date documentation on GemFire 7.0.x. The vFabric GemFire 7.0 documentation site will no longer be updated.

How Function Execution Works

Where Functions Are Executed

You can execute data-independent functions or data-dependent functions in vFabric GemFire. You run data-independent functions by targeting a specific member or specific members in your distributed system, or by targeting logical member groups on which to execute your function. If you are executing a data-dependent function, you specify a region on which to execute the function.
  • On a specific member or members. Execute the function in your own distributed system, and specify the member or members where you want to run the function.
  • On a specific server or set of servers. If you are connected to a distributed system as a client, you can execute the function on a server or servers configured for a specific connection pool, or on a server or servers connected to a given cache.
  • On member groups or on a single member within each member group. In GemFire 7.0, you can organize members into logical member groups. (See Using Member Groups for more information.) You can invoke a data independent function on all members in a specified member group (or member groups) or execute the function on only one member of each specified member group.
  • On a data set. Specify a region and possibly a set of keys on which to run the function.

See the com.gemstone.gemfire.cache.execute.FunctionService Java API documentation for more details.

How Functions Are Executed

The following things occur when a function is executed:
  1. When you call the execute method on the Function Execution object, the execution is sent to all members where it needs to run. The locations are determined by the FunctionService on* method calls, region configuration, and any filters. With onRegion, for a client region, the function is sent to the server system. For a non-client region, the function is handled in the calling application’s distributed system.
  2. If the function has results, the result is returned to the execute method call in a ResultCollector object.
  3. The originating member collects results using ResultCollector.getResult.

Highly Available Functions

Generally, function execution errors are returned to the calling application. You can code for high availability for onRegion functions that return a result, so GemFire automatically retries a function if it does not execute successfully. To be highly available, the function must be coded and configured for it, and the calling application must invoke the function using the results collector getResult method.

When a failure occurs (such as an execution error or member crash while executing), the system responds as follows:
  1. Waits for all calls to return
  2. Sets a boolean indicating a re-execution is being done
  3. Calls the result collector’s clearResults method
  4. Executes the function

For client regions, the system retries the execution according to com.gemstone.gemfire.cache.client.Pool retryAttempts. If the function fails to run every time, the final exception is returned to the getResult method.

For member calls, the system retries until it succeeds or no data remains in the system for the function to operate on.

Function Execution Scenarios

The diagram shows the sequence of events for a data-independent function run on a client's server. The function is executed against all available servers:



The next figure shows the sequence of events for a data-independent function executed against all available members in the calling application’s distributed system:



The next figure shows a data-dependent function run on a client region. The client region is connected to the server system, where the region is partitioned, so the function automatically goes to the server system to run against all servers holding data for the region.



The next figure shows the same data-dependent function with the added specification of a set of keys on which to run. Servers that do not hold any keys are left out of the function execution.



The next figure shows a data-dependent call is on a region that is not configured as a client region, so it runs in the caller’s distributed system.



The next figure demonstrates a sequence of steps in a call to a highly available function. The call fails the first time on one of the participating members and is successfully run a second time on all members.