Lifetime of method arguments and return values

PODS defines the following policies for the lifetime of arguments to PODS methods and of values returned from methods. Methods implemented by M-Business Client's browser objects follow these policies, so you should follow these policies whenever you call M-Business Client browser methods. In addition, any methods you define in a POD must follow these policies. M-Business Client follows these policies whenever it calls your methods, just as M-Business JavaScript engine code calls a method of an object you have implemented.

  • Any string passed to a PODS method is guaranteed to remain valid only for the method call. If a method implementation wants to keep a pointer to the string's characters, that method must create its own private copy of the string.

  • Code that calls a PODS method and receives an object or string in return is not responsible for freeing the returned object or string.

  • Any string returned by a PODS method is guaranteed to remain valid only until the next call to any PODS method.

    A caller that wants to keep a pointer to a returned string's characters must immediately copy the characters upon return from the method. Note that for PODS objects defined by M-Business Client, returned strings actually are guaranteed to remain valid somewhat longer, until the current event handler has finished execution.

  • Any object returned by a PODS method is guaranteed to remain valid for as long as the M-Business Client browser remains on the current page, but you may release it and free up the memory earlier. See Reference counting: registering and freeing objects.

As a PODS author, you must make sure that all strings and objects returned by your POD follow these rules. In particular, be sure that all dynamically allocated memory is freed. The best way to ensure that dynamic memory is freed is to use PODSMemoryMgr methods to register strings. Any string registered by stringRegister() is automatically freed when the current event handler is finished. See stringRegister( ).

Copyright © 2008, iAnywhere Solutions, Inc.