allocate

typedef [allocate (allocate-option-list) [, type-attribute-list] ] type-name;

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 group. 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.

Examples

/* ACF file */

typedef [allocate(all_nodes, dont_free)] PTYPE1;

typedef [allocate(all_nodes)] PTYPE2;

typedef [allocate(dont_free)] PTYPE3;

Remarks

The ACF type attribute allocate lets you customize memory allocation and deallocation for a type defined in the IDL file. These are the 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.

Note that when applied to types used for in, out parameters, any parameter that is a pointer to a type qualified with the all_nodes option will cause a reallocation when the data is unmarshalled. It is the responsibility of the application to free the previously allocated memory corresponding to this parameter. For example:

typedef struct foo

{

[string] char * PFOO;

} * PFOO

void proc1 ( [in,out] PFOO * ppfoo);

The data type PFOO will be reallocated in the out direction by the stub before unmarshalling. Therefore, the previously allocated area must be freed by the application or a memory leak will occur.