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, consider 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.