.\" Automatically generated by Pandoc 2.17.1.1
.\"
.TH "MINIASYNC_VDM" "7" "2022-09-04" "MINIASYNC - miniasync version 0.2.1" "MINIASYNC Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2020-2022, Intel Corporation
.SH NAME
.PP
\f[B]miniasync_vdm\f[R] - virtual data mover API for miniasync library
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libminiasync.h>

typedef void *(*vdm_operation_new)
    (struct vdm *vdm, const enum vdm_operation_type type);
typedef int (*vdm_operation_start)(void *data,
    const struct vdm_operation *operation,
    struct future_notifier *n);
typedef enum future_state (*vdm_operation_check)(void *data,
    const struct vdm_operation *operation);
typedef void (*vdm_operation_delete)(void *data,
    const struct vdm_operation *operation,
    struct vdm_operation_output *output);

struct vdm {
    vdm_operation_new op_new;
    vdm_operation_delete op_delete;
    vdm_operation_start op_start;
    vdm_operation_check op_check;
    unsigned capabilities;
};

enum vdm_operation_type {
    VDM_OPERATION_MEMCPY,
    VDM_OPERATION_MEMMOVE,
    VDM_OPERATION_MEMSET,
    VDM_OPERATION_FLUSH,
};

enum vdm_operation_result {
    VDM_SUCCESS,
    VDM_ERROR_OUT_OF_MEMORY,
    VDM_ERROR_JOB_CORRUPTED,
};

struct vdm_operation_data {
    void *data;
    struct vdm *vdm;
    struct vdm_operation operation;
};

struct vdm_operation_output {
    enum vdm_operation_type type;
    enum vdm_operation_result result;
    union {
        struct vdm_operation_output_memcpy memcpy;
        struct vdm_operation_output_memmove memmove;
        struct vdm_operation_output_memset memset;
        struct vdm_operation_output_flush flush;
    } output;
};
\f[R]
.fi
.PP
For general description of miniasync, see \f[B]miniasync\f[R](7).
.SH DESCRIPTION
.PP
Virtual data mover API forms the basis of various concrete data movers.
It is an abstraction that the data mover implementations should adapt
for compatibility with the \f[B]miniasync_future\f[R](7) feature.
.PP
\f[I]struct vdm\f[R] is a structure required by every virtual data mover
operation, for example \f[B]vdm_memcpy\f[R](3).
\f[I]struct vdm\f[R] has following members:
.IP \[bu] 2
\f[I]op_new\f[R] - allocations needed for the specified operation type
.IP \[bu] 2
\f[I]op_delete\f[R] - deallocations and finalizations of operation
.IP \[bu] 2
\f[I]op_start\f[R] - populates operation data and starts the execution
of the task
.IP \[bu] 2
\f[I]op_check\f[R] - data mover task status check
.PP
Currently, virtual data mover API supports following operation types:
.IP \[bu] 2
\f[B]VDM_OPERATION_MEMCPY\f[R] - a memory copy operation
.IP \[bu] 2
\f[B]VDM_OPERATION_MEMMOVE\f[R] - a memory move operation
.IP \[bu] 2
\f[B]VDM_OPERATION_MEMSET\f[R] - a memory set operation
.IP \[bu] 2
\f[B]VDM_OPERATION_FLUSH\f[R] - a cache flush operation
.PP
For more information about concrete data mover implementations, see
\f[B]miniasync_vdm_threads\f[R](7),
\f[B]miniasync_vdm_synchronous\f[R](7) and
\f[B]miniasync_vdm_dml\f[R](7).
.PP
For more information about the usage of virtual data mover API, see
\f[I]examples\f[R] directory in miniasync repository
<https://github.com/pmem/miniasync>.
.SS RETURN VALUE
.PP
The vdm operations always return a new instance of a
\f[V]vdm_operation_future\f[R] structure.
If initialization is successful, this future is idle and ready to be
polled.
Otherwise, the future is immediately complete and the specific error can
be read from the \f[I]result\f[R] field of the
\f[I]vdm_operation_output\f[R] structure.
Already complete can also be safely polled, which has no effect.
Depending on the vdm implementation, the operation\[cq]s processing can
also fail, in which case the error can be similarly found in the same
location.
.PP
The \f[I]result\f[R] field can be set to one of the following values:
.IP \[bu] 2
\f[B]VDM_ERROR_OUT_OF_MEMORY\f[R] - data mover has insufficient memory
to create a a new operation.
This usually indicates that there are too many pending operations.
.IP \[bu] 2
\f[B]VDM_ERROR_JOB_CORRUPTED\f[R] - data mover encountered an error
during internal job processing.
The specific cause depends on the implementation.
.SH SEE ALSO
.PP
\f[B]vdm_flush\f[R](3), \f[B]vdm_memcpy\f[R](3),
\f[B]vdm_memmove\f[R](3), \f[B]vdm_memset\f[R](3),
\f[B]miniasync\f[R](7), \f[B]miniasync_future\f[R](7),
\f[B]miniasync_vdm_dml\f[R](7), \f[B]miniasync_vdm_synchronous\f[R](7),
\f[B]miniasync_vdm_threads\f[R](7) and \f[B]<https://pmem.io>\f[R]