Stub-Allocated Buffers

Rather than forcing a distinct call for each node of the tree or graph, you can direct the stubs to compute the size of the data and to allocate and free memory by making a single call to midl_user_allocate or midl_user_free. The ACF attribute [allocate(all_nodes)] directs the stubs to allocate or free all nodes in a single call to the user supplied–memory management functions.

For example, an RPC application might use the following binary tree data structure:

/* IDL file fragment */
typedef struct _TREE_TYPE 
{
    short sNumber;
    struct _TREE_TYPE * pLeft;
    struct _TREE_TYPE * pRight;
} TREE_TYPE;

typedef TREE_TYPE * P_TREE_TYPE;

The ACF attribute [allocate(all_nodes)] applied to this data type appears in the typedef declaration in the ACF as:

/* ACF file fragment */
typedef [allocate(all_nodes)] P_TREE_TYPE;

The [allocate] attribute can only be applied to pointer types. The [allocate] ACF attribute is a Microsoft extension to DCE IDL and, as such, is not available if you compile with the MIDL /osf switch. When [allocate(all_nodes)] is applied to a pointer type, the stubs generated by the MIDL compiler traverse the specified data structure to determine the allocation size. The stubs then make a single call to allocate the entire amount of memory needed by the graph or tree. A client application can free memory much more efficiently by making a single call to midl_user_free. However, server-stub performance is generally increased when using node-by-node memory allocation because the server stubs can often use private memory that requires no allocations.

For additional information, see Node-by-Node Allocation and Deallocation.