Category: Proxy usage
Why do all proxy methods have two default arguments of type xmog_localenv * and type xmog_flags?
These arguments allow you to pass some additional knowledge to the method call, thereby potentially improving the performance of the call. As you might know, just about every JNI call requires a JNIEnv* to be passed as the first call argument. xmog_localenv is the Codemesh runtime abstraction around a JNIEnv and other framework-related information elements. If no xmog_localenv is passed to a method invocation, one has to be retrieved from threadlocal storage. This can take additional time that would not be taken if you passed an xmog_localenv* to the call.
Clearly, this optimization makes the most sense if you have a tight loop with repeated invocations or a similar situation. Consider the following two snippets, both representing valid code, but the second probably performing somewhat better:
// unoptimized loop for( int i=0; i<1000000; i++ ) myProxyObj.call( 0, 1 );
// optimized loop xmog_localenv * lenv = xmog_localenv::get_instance( (xmog_localenv*)NULL );
for( int i=0; i<1000000; i++ ) myProxyObj.call( 0, 1, lenv );
We recommend that you don't prematurely optimize and saddle yourself with the burden of acqiring and passing an xmog_localenv* to proxy methods.
The xmog_flags parameter allows you a degree of control over the type of JNI reference returned by an API call. You should never have to use this parameter explicitly, but the framework takes advantage of it internally.