udi_cb_alloc_batch(3udi)

---

Allocate a batch of control blocks with buffers

SYNOPSIS

#include <udi.h>

void udi_cb_alloc_batch (

	udi_cb_alloc_batch_call_t *callback,

	udi_cb_t *gcb,

	udi_index_t cb_idx,

	udi_index_t count,

	udi_boolean_t with_buf,

	udi_size_t buf_size,

	udi_buf_path_t path_handle );
 
typedef void udi_cb_alloc_batch_call_t (

	udi_cb_t *gcb,

	udi_cb_t *first_new_cb );
 

ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".

cb_idx is a control block index that indicates required properties of the control block, such as metalanguage type and scratch size. All of the control blocks allocated will be of the same type as indicated by this cb_idx.

count is the number of control blocks of this type to allocate in the batch operation.

with_buf is true if buffers should be allocated along with the control blocks. If true, a buffer of size buf_size will be allocated for each udi_buf_t pointer (UDI_DL_BUF layout entry) that exists in each allocated control block. If false, no buffers will be allocated and the values of the corresponding control block buffer pointers are undefined.

buf_size is the size of the buffers to be allocated if with_buf is true. This argument is ignored if with_buf is false.

path_handle is the handle identifying the intended use and dispatching of the allocated buffers. Path handle usage is determined by the driver, but by associating the use of a specific path_handle with buffers allocated for a specific purpose, the driver allows the environment to predict and optimize the allocated buffer requirements. This field is ignored if with_buf is false.

first_new_cb is a pointer to the first allocated control block in the list of returned control blocks. If count is zero, first_new_cb will be NULL.

DESCRIPTION This service combines the use of udi_cb_alloc with UDI_BUF_ALLOC to allocate batches of one or more control blocks with optional associated buffers.

Consult udi_cb_alloc for more specifics on how the individual control blocks will be allocated and initialized.

Consult UDI_BUF_ALLOC and udi_buf_write for more specifics on how the individual buffers will be allocated and initialized.

The control blocks are returned to the caller by passing them as a chain or list. If the control block type allows control block chaining (i.e. the control block contains a pointer to another control block of the same type) then the chain field within the control blocks are used to link the returned control blocks: each control block's chain field will point to the next control block in the chain. If the control block type does not support chaining, then the initiator_context field of the returned control blocks is used to link the control blocks; the callback function should unlink the control blocks and reset the initiator_context as appropriate. The link pointer in the last control block shall be set to NULL.

WARNINGS See the warnings for udi_cb_alloc.

Batch allocated control blocks must be unlinked before use unless actually used as a chain. Passing a control block to a channel operation or system service call relenquishes ownership of that control block and any chained control blocks. If the list is maintained via the initiator_context, the driver is assured that the initiator_context will be returned unchanged, but is not guaranteed that the initiator_context will not be changed (or deallocated) while the driver does not own the control block.

REFERENCES udi_cb_t, udi_cb_alloc, udi_buf_t, UDI_BUF_ALLOC, udi_buf_write