Chapter 12: Parameter Passing Rules

This chapter discusses the parameter passing rules followed by the VisiBroker IDL to C++ compiler. It includes the following major sections:

Implicit Arguments

Explicit Arguments

Primitive Data Types

Complex Data Types

T_var Data Types

Implicit Arguments

Arguments can be passed using contexts as defined in IDL. For more information, see The Common Object Request Broker: Architecture and Specification - 96-03-04. This document is available from the Object Management Group and describes the architectural details of CORBA.

Explicit Arguments

When you specify an interface in IDL, arguments you pass to methods that are returned may be one listed below:

in - Parameter used as input only.

out - Parameter used to hold an output result.

inout - Parameter used both as input and to hold an output result.

return - Result of an operation on an interface.

Primitive Data Types

The following section summarizes the parameter passing mode for primitive data types.

Data Type: short

In: Short

Inout: Short&

Out: Short&

Return: Short

Data Type: unsigned short

In: UShort

Inout: UShort&

Out: UShort&

Return: UShort

Data Type: long

In: Long

Inout: Long&

Out: Long&

Long

Data Type: unsigned long

In: ULong

Inout: ULong&

Out: ULong&

Return: ULong

Data Type: float

In: Float

Inout: Float&

Out: Float&

Return: Float

Data Type: double

In: Double

Inout: Double&

Out: Double&

Return: Double

Data Type: boolean

In: Boolean

Inout: Boolean&

Out: Boolean&

Return: Boolean

Data Type: char

In: Char

Inout: Char&

Out: Char&

Return: Char

Data Type: octet

In: Octet

Inout: Octet&

Out: Octet&

Return: Octet

Data Type: enum

In: enum

Inout: enum&

Out: enum&

Return: enum

Memory Management

The following are the memory management rules for all primitive data types and parameter passing modes. The mode is given first followed by the description.

in - The caller allocates the necessary storage and initializes it. The callee uses the value.

out - The caller allocates the necessary storage, but need not initialize it. The callee must set the value.

inout - The caller allocates the necessary storage and initializes it. The callee may change the value.

return - The callee initializes and returns the data by value. The caller receives the value.

Complex Data Types

Parameter and memory management rules for aggregate data types are more complex. The issue of when memory is allocated and freed deserves special attention. The following section summarizes the parameter passing rules for complex data types.

Data Type: object reference pointer

In: objref_ptr

Inout: objref_ptr &

Out: objref_ptr &

Return: objref_ptr

Data Type: struct, fixed length

In: const struct &

Inout: struct &

Out: struct &

Return: struct

Data Type: struct, variable length

In: const struct &

Inout: struct &

Out: struct *&

Return: struct *

Data Type: union, fixed length

In: const union &

Inout: union &

Out: union &

Return: union

Data Type: union, variable length

In: const union &

Inout: union &

Out: union *&

Return: union *

Data Type: string

In: const char *

Inout: char *&

Out: char *&

Return: char *

Data Type: sequence

In: const sequence &

Inout: sequence &

Out: sequence *&

Return: sequence *

Data Type: array, fixed length

In: const array

Inout: array

Out: array

Return: array slice *

Data Type: array, variable length

In: const array

Inout: array

Out: array slice *&

Return: array slice *

Data Type: any

In: const any &

Inout: any &

Out: any *&

Return: any *

Memory Management

The memory management rules for complex data types vary, depending on the passing mode and the type of the parameter. The following sections describe the rules for each parameter type.

Object Reference Pointers

The following section lists memory management rules for object reference pointers.

in - The caller allocates the necessary storage for the object reference and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the object reference by invoking the _duplicate method.

out - The caller allocates the necessary storage, but need not initialize it. Once the method returns, the storage will hold an object reference and the caller is responsible for releasing it when finished. On the server side, the ORB allocates the memory and the callee must provide the object reference. Once the data has been sent to the client, the ORB invokes the _release method on the reference to decrement its reference count.

inout - The caller allocates the necessary storage and initializes it. If the callee modifies the object reference, the ORB will release the old object and assign it a new value. If the caller wants to continue to use the object reference, it must invoke the _duplicate method prior to passing it to the callee. On the server side, the ORB will allocate memory for the reference. If the callee wishes to assign a new value to the object reference, it must first invoke the _release method.

return - On the server side, the callee initializes and returns the object reference. The ORB will invoke _release on the object reference once it has been returned to the caller. The caller receives the object reference and is responsible for releasing it.

Fixed Structures and Unions

The following section lists memory management rules for fixed-length structures and unions.

in - The caller allocates the necessary storage for the structure and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the structure by copying it.

out - The caller allocates the necessary storage, but need not initialize it. Once the method returns, the storage will hold the structure and the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates the memory and the callee must set the value. Once the data has been sent to the client, the ORB releases the memory.

inout - The caller allocates the necessary storage and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the structure. The callee may assign a new value to the structure. Once the structure is returned to the client, the ORB releases the memory.

return - On the server side, the callee initializes and returns the data by value. The caller receives the structure by value.

Variable Structures and Unions

The following section lists memory management rules for variable-length structures and unions.

in - The caller allocates the necessary storage for the structure and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the structure by copying it.

out - The caller allocates a pointer and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer and passes it by reference to the callee. The callee sets the pointer to a valid instance of the parameter's type. If the callee wishes to keep the data buffer, it is must make a copy.

inout - The caller allocates the necessary storage and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the structure. If the callee wishes to change the value, it must first release the old data prior to assigning it a new value. Once the data is returned to the client, the ORB releases the memory.

return - On the server side, the callee returns to the ORB a pointer to the data buffer. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a pointer to the structure or union. If the caller wishes to modify any of the values, it must make a copy of the structure or union and modify the copy. The caller is responsible for releasing the memory.

Strings

The following section lists the memory management rules for strings.

in - The caller allocates the necessary storage for the string and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the string by copying it.

out - The caller allocates a pointer and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer and passes it by reference to the callee. The callee sets the pointer to a valid instance of the parameter's type. If the callee wishes to keep the data buffer, it is must make a copy. The callee is not allowed to return a NULL pointer.

inout - The caller allocates the necessary storage for both input string the char * pointing to it. Upon return, the caller must release the memory using the string_free method. The ORB will delete the old buffer and allocate a new buffer for the out parameter. The size of the output string may be larger that the input string. On the server side, the ORB will allocate memory for the string. To return a new string, the callee must free the old memory using string_free and allocate new storage using the string_alloc method. Once the data is returned to the client, the ORB releases the memory. The callee may not return a NULL pointer.

return - On the server side, the callee returns to the ORB a pointer to the data buffer. The buffer must have been allocated using string_alloc. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a char * pointer to the string. If the caller wishes to modify any of the values, it must make a copy of the string and modify the copy. The caller is responsible for releasing the memory using string_free.

Sequences and Type-safe Arrays

The following section lists memory management rules for sequences and any arrays.

in - The caller allocates the necessary storage for the structure and is responsible for freeing it when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the data buffer by copying it or increasing the object's reference count.

out - The caller allocates a pointer and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer and passes it by reference to the callee. The callee sets the pointer to a valid instance of the parameter's type. If the callee wishes to keep the data buffer, it is must make a copy or increase the object's reference count.

inout - The caller allocates the sequence or any and initializes it. The ORB may free the old buffer and allocate a new buffer for the output parameter., depending on the state of the boolean release parameter used to construct the object. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the structure. The callee may free the old buffer and allocate a new buffer, depending on the state of the boolean release parameter used to construct the object. Once the data is returned to the client, the ORB releases the memory.

return - On the server side, the callee returns to the ORB a pointer to the sequence or any. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a pointer to the sequence or any. If the caller wishes to modify any of the values, it must make a copy of the object and modify the copy. The caller is responsible for releasing the returned object's memory.

Fixed Arrays

The following section lists memory management rules for fixed-length arrays.

in - The caller allocates the necessary storage for the array and is responsible for freeing it when finished. The callee receives the array from the ORB and cannot modify it. The memory associated with the array is freed by the ORB upon returning. The callee can preserve the array by copying it.

out - The caller allocates the necessary storage, but need not initialize it. Once the method returns, the storage will hold the array and the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates the memory and the callee initializes the array. Once the array has been sent to the client, the ORB releases the memory.

inout - The caller allocates the necessary storage and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the array. The callee may the elements in the array. Once the array has been returned to the client, the ORB releases the memory.

return - On the server side, the callee returns a pointer to the array slice. The callee may not return a NULL pointer. The caller receives a pointer to the array slice, but may not modify it. If the caller wishes to modify any of the elements, it must make a copy of the array slice and modify the copy. The caller is responsible for releasing the returned array slice's memory.

Variable-Length Arrays

The following section lists memory management rules for variable-length arrays.

in - The caller allocates the necessary storage for the array and initializes it. The caller is responsible for freeing the memory when finished. The callee receives the parameter from the ORB and cannot modify it. The memory associated with the parameter is freed by the ORB upon returning. The callee can preserve the array by copying it.

out - The caller allocates a pointer to an array slice and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer to an array slice and passes it by reference to the callee. The callee sets the pointer to a valid instance of an array. Once the data is returned, the ORB will free the storage. The callee is not allowed to return a NULL pointer.

inout - The caller allocates the array and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the array. The callee may modify elements of the array. Once the data is returned to the client, the ORB releases the memory.

return - On the server side, the callee returns to the ORB a pointer to an array slice. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a pointer to the array slice. If the caller wishes to modify any of the elements, it must make a copy of the array and modify the copy. The caller is responsible for releasing the memory.

T_var Data Types

The following section summarizes the parameter passing mode for T_var data types.

Data type: object ref var

In: const objref_var&

Inout: objref_var&

Out: objref_var&`

Return: objref_var

Data type: struct_var

In: const struct_var&

Inout: struct_var&

Out: struct_var&

Return: struct_var

Data type: union_var

In: const union_var&

Inout: union_var&

Out: union_var&

Return: union_var

Data type: string_var

In: const string_var&

Inout: string_var&

Out: string_var&

Return: string_var

Data type: sequence_var

In: const sequence_var&

Inout: sequence_var&

Out: sequence_var&

Return: sequence_var

Data type: array_var

In: const array_var&

Inout: array_var&

Out: array_var&

Return: array_var

Data type: any_var

In: const any_var&

Inout: any_var&

Out: any_var&

Return: any_var

Memory Management for T_var Types

The following section lists the memory management rules for sequences and any arrays.

in - The caller allocates the necessary storage for the object and is responsible for freeing it when finished. The callee receives the object from the ORB and cannot modify it. The memory associated with the object is freed by the ORB upon returning. The callee can preserve the object by copying it or increasing the object's reference count.

out - The caller allocates a pointer and passes it by reference to the ORB. Once the method returns, the caller is responsible for freeing the memory when finished. On the server side, the ORB allocates a pointer and passes it by reference to the callee. The callee sets the pointer to a valid instance of the parameter's type. If the callee wishes to preserve the object, it is must make a copy or increase the object's reference count.

inout - The caller allocates the sequence or any and initializes it. Upon return, the caller must release the memory. On the server side, the ORB will allocate memory for the object. Once the data is returned to the client, the ORB releases the memory. If the callee wishes to preserve the object, it is must make a copy or increase the object's reference count.

return - On the server side, the callee returns to the ORB a pointer to the object. The ORB will free the memory upon returning. The client cannot return a NULL pointer. The caller receives a pointer to the object. The caller is responsible for releasing the returned object's memory.


[Preface] [Chapter 1] [Chapter 2] [Chapter 3] [Chapter 4] [Chapter 5] [Chapter 6]
[Chapter 7] [Chapter 8] [Chapter 9] [Chapter 10] [Chapter 11] [Chapter 12] [Appendix A]