allocate attribute
The [allocate] ACF attribute lets you customize memory allocation and deallocation for a type defined in the IDL file.
typedef [allocate (allocate-option-list) [, type-attribute-list] ] type-name;
Parameters
-
allocate-option-list
-
Specifies one or more memory-allocation options. Select one of either single_node or all_nodes, or one of either free or dont_free, or one from each pair. When you specify more than one option, separate the options with commas.
-
type-attribute-list
-
Specifies other optional ACF-type attributes. When you specify more than one type attribute, separate the options with commas.
-
type-name
-
Specifies a type defined in the IDL file.
Remarks
The [allocate] attribute has the following valid options.
| Option | Description |
|---|---|
| all_nodes | Makes one call to allocate and free memory for all nodes. |
| single_node | Makes many individual calls to allocate and free each node of memory. |
| free | Frees memory on return from the server stub. |
| dont_free | Does not free memory on return from the server stub. |
By default, the stubs may allocate storage for data referenced by a unique or full pointer by calling midl_user_allocate and midl_user_free individually for each pointer.
You can optimize the speed of your application by specifying the option all_nodes. This option directs the stub to compute the size of all memory referenced through the pointer of the specified type and to make a single call to midl_user_allocate. The stub releases the memory by making one call to midl_user_free.
The dont_free option directs the MIDL compiler to generate a server stub that does not call midl_user_free for the specified type. The dont_free option allows the pointer structures to remain accessible to the server application after the remote procedure call has completed and returned to the client.
The [allocate] attribute will cause any [in, out] parameter that is a pointer to a type qualified with the all_nodes option to reallocate memory when the data is unmarshaled. It is the responsibility of the application to free the memory allocated previously for this parameter. For example:
typedef struct thistype
{
[string] char * PTHISTYPE;
} * PTHISTYPE
HRESULT proc1 ( [in,out] PTHISTYPE * ppthistype);
The data type PTHISTYPE will be reallocated in the [out] direction by the stub before unmarshaling. Therefore, the application must free the memory it previously allocated for this parameter's data, or a memory leak will occur.
Examples
/* ACF file */
typedef [allocate(all_nodes, dont_free)] PTYPE1;
typedef [allocate(all_nodes)] PTYPE2;
typedef [allocate(dont_free)] PTYPE3;
See also