Function ucp_mem_map

pub unsafe extern "C" fn ucp_mem_map(
    context: ucp_context_h,
    params: *const ucp_mem_map_params_t,
    memh_p: *mut ucp_mem_h,
) -> ucs_status_t

@ingroup UCP_MEM @brief Map or allocate memory for zero-copy operations.

This routine maps or/and allocates a user-specified memory segment with @ref ucp_context_h “UCP application context” and the network resources associated with it. If the application specifies NULL as an address for the memory segment, the routine allocates a mapped memory segment and returns its address in the @a address_p argument. The network stack associated with an application context can typically send and receive data from the mapped memory without CPU intervention; some devices and associated network stacks require the memory to be mapped to send and receive data. The @ref ucp_mem_h “memory handle” includes all information required to access the memory locally using UCP routines, while @ref ucp_rkey_h “remote registration handle” provides an information that is necessary for remote memory access.

@note Another well know terminology for the “map” operation that is typically used in the context of networking is memory “registration” or “pinning”. The UCP library registers the memory the available hardware so it can be assessed directly by the hardware.

Memory mapping assumptions: @li A given memory segment can be mapped by several different communication stacks, if these are compatible. @li The @a memh_p handle returned may be used with any sub-region of the mapped memory. @li If a large segment is registered, and then segmented for subsequent use by a user, then the user is responsible for segmentation and subsequent management.

Matrix of behavior

parameter/flag	@ref UCP_MEM_MAP_NONBLOCK "NONBLOCK"	@ref UCP_MEM_MAP_ALLOCATE "ALLOCATE"	@ref UCP_MEM_MAP_FIXED "FIXED"	@ref ucp_mem_map_params.address "address"	@b result
@b value	0/1 - the value\n only affects the\n register/map\n phase	0	0	0	@ref anch_err "error" if length > 0
		1	0	0	@ref anch_alloc_reg "alloc+register"
		0	1	0	@ref anch_err "error"
		0	0	defined	@ref anch_reg "register"
		1	1	0	@ref anch_err "error"
		1	0	defined	@ref anch_alloc_hint_reg "alloc+register,hint"
		0	1	defined	@ref anch_err "error"
		1	1	defined	@ref anch_alloc_fixed_reg "alloc+register,fixed"

@note @li \anchor anch_reg @b register means that the memory will be registered in corresponding transports for RMA/AMO operations. This case intends that the memory was allocated by user before. @li \anchor anch_alloc_reg @b alloc+register means that the memory will be allocated in the memory provided by the system and registered in corresponding transports for RMA/AMO operations. @li \anchor anch_alloc_hint_reg alloc+register,hint means that the memory will be allocated with using @ref ucp_mem_map_params.address as a hint and registered in corresponding transports for RMA/AMO operations. @li \anchor anch_alloc_fixed_reg alloc+register,fixed means that the memory will be allocated and registered in corresponding transports for RMA/AMO operations. @li \anchor anch_err @b error is an erroneous combination of the parameters.

@param [in] context Application @ref ucp_context_h “context” to map (register) and allocate the memory on. @param [in] params User defined @ref ucp_mem_map_params_t configurations for the @ref ucp_mem_h “UCP memory handle”. @param [out] memh_p UCP @ref ucp_mem_h “handle” for the allocated segment.

@return Error code as defined by @ref ucs_status_t