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]