na.h

Go to the documentation of this file.

/*
 * Copyright (C) 2013 Argonne National Laboratory, Department of Energy,
 *                    UChicago Argonne, LLC and The HDF Group.
 * All rights reserved.
 *
 * The full copyright notice, including terms governing use, modification,
 * and redistribution, is contained in the COPYING file that can be
 * found at the root of the source code distribution tree.
 */

#ifndef NA_H
#define NA_H

#include "na_config.h"

#include <limits.h>

typedef struct na_class na_class_t;     /* Opaque NA class */
typedef struct na_context na_context_t; /* Opaque NA execution context */
typedef void *na_addr_t;                /* Abstract NA address */
typedef na_uint64_t na_size_t;          /* Size */
typedef na_uint32_t na_tag_t;           /* Tag */
typedef void *na_op_id_t;               /* Abstract operation id */

typedef void *na_mem_handle_t;          /* Abstract memory handle */
typedef na_uint64_t na_offset_t;        /* Offset */

/* Segment */
struct na_segment {
    na_ptr_t address; /* Address of the segment */
    na_size_t size;   /* Size of the segment in bytes */
};

/* Constant values */
#define NA_ADDR_NULL       ((na_addr_t)0)
#define NA_OP_ID_NULL      ((na_op_id_t)0)
#define NA_OP_ID_IGNORE    ((na_op_id_t *)1)
#define NA_MEM_HANDLE_NULL ((na_mem_handle_t)0)

/* Max timeout */
#define NA_MAX_IDLE_TIME (3600*1000)

/* Tag upper bound
 * NB. This is not the user tag limit but only the limit imposed by the type */
#define NA_TAG_UB UINT_MAX

/* Max len used for strings that represent an addr */
#define NA_MAX_ADDR_LEN 256

/* The memory attributes associated with the memory handle
 * can be defined as read/write or read only */
#define NA_MEM_READWRITE  0x00
#define NA_MEM_READ_ONLY  0x01

/* Error return codes:
 * Functions return 0 for success or NA_XXX_ERROR for failure */
typedef enum na_return {
    NA_SUCCESS,          /* operation succeeded */
    NA_CANCELED,         /* operation was canceled */
    NA_TIMEOUT,          /* reached timeout */
    NA_INVALID_PARAM,    /* invalid parameter */
    NA_SIZE_ERROR,       /* message size error */
    NA_ALIGNMENT_ERROR,  /* alignment error */
    NA_PERMISSION_ERROR, /* read/write permission error */
    NA_NOMEM_ERROR,      /* no memory error */
    NA_PROTOCOL_ERROR    /* unknown error reported from the protocol layer */
} na_return_t;

/* Callback operation type */
typedef enum na_cb_type {
    NA_CB_LOOKUP,
    NA_CB_SEND_UNEXPECTED,
    NA_CB_RECV_UNEXPECTED,
    NA_CB_SEND_EXPECTED,
    NA_CB_RECV_EXPECTED,
    NA_CB_PUT,
    NA_CB_GET
} na_cb_type_t;

/* Callback info structs */
struct na_cb_info_lookup {
    na_addr_t addr;
};

struct na_cb_info_recv_unexpected {
    na_size_t actual_buf_size;
    na_addr_t source;
    na_tag_t  tag;
};

/* Callback info struct */
struct na_cb_info {
    void *arg;         /* User data */
    na_return_t ret;   /* Return value */
    na_cb_type_t type; /* Callback type */
    union {            /* Union of callback info structures */
        struct na_cb_info_lookup lookup;
        struct na_cb_info_recv_unexpected recv_unexpected;
    } info;
};

/* Callback type */
typedef na_return_t (*na_cb_t)(const struct na_cb_info *callback_info);

#ifdef __cplusplus
extern "C" {
#endif

NA_EXPORT na_class_t *
NA_Initialize(
        const char *info_string,
        na_bool_t   listen
        ) NA_WARN_UNUSED_RESULT;

NA_EXPORT na_return_t
NA_Finalize(
        na_class_t *na_class
        );

NA_EXPORT na_context_t *
NA_Context_create(
        na_class_t *na_class
        );

NA_EXPORT na_return_t
NA_Context_destroy(
        na_class_t   *na_class,
        na_context_t *context
        );

NA_EXPORT na_return_t
NA_Addr_lookup(
        na_class_t   *na_class,
        na_context_t *context,
        na_cb_t       callback,
        void         *arg,
        const char   *name,
        na_op_id_t   *op_id
        );

NA_EXPORT na_return_t
NA_Addr_lookup_wait(
        na_class_t *na_class,
        const char *name,
        na_addr_t  *addr
        );

NA_EXPORT na_return_t
NA_Addr_free(
        na_class_t *na_class,
        na_addr_t   addr
        );

NA_EXPORT na_return_t
NA_Addr_self(
        na_class_t *na_class,
        na_addr_t  *addr
        );

NA_EXPORT na_return_t
NA_Addr_dup(
        na_class_t *na_class,
        na_addr_t   addr,
        na_addr_t  *new_addr
        );

NA_EXPORT na_bool_t
NA_Addr_is_self(
        na_class_t *na_class,
        na_addr_t   addr
        );

NA_EXPORT na_return_t
NA_Addr_to_string(
        na_class_t *na_class,
        char       *buf,
        na_size_t   buf_size,
        na_addr_t   addr
        );

NA_EXPORT na_size_t
NA_Msg_get_max_expected_size(
        na_class_t *na_class
        ) NA_WARN_UNUSED_RESULT;

NA_EXPORT na_size_t
NA_Msg_get_max_unexpected_size(
        na_class_t *na_class
        ) NA_WARN_UNUSED_RESULT;

NA_EXPORT na_tag_t
NA_Msg_get_max_tag(
        na_class_t *na_class
        ) NA_WARN_UNUSED_RESULT;

NA_EXPORT na_return_t
NA_Msg_send_unexpected(
        na_class_t   *na_class,
        na_context_t *context,
        na_cb_t       callback,
        void         *arg,
        const void   *buf,
        na_size_t     buf_size,
        na_addr_t     dest,
        na_tag_t      tag,
        na_op_id_t   *op_id
        );

NA_EXPORT na_return_t
NA_Msg_recv_unexpected(
        na_class_t   *na_class,
        na_context_t *context,
        na_cb_t       callback,
        void         *arg,
        void         *buf,
        na_size_t     buf_size,
        na_op_id_t   *op_id
        );

NA_EXPORT na_return_t
NA_Msg_send_expected(
        na_class_t   *na_class,
        na_context_t *context,
        na_cb_t       callback,
        void         *arg,
        const void   *buf,
        na_size_t     buf_size,
        na_addr_t     dest,
        na_tag_t      tag,
        na_op_id_t   *op_id
        );

NA_EXPORT na_return_t
NA_Msg_recv_expected(
        na_class_t   *na_class,
        na_context_t *context,
        na_cb_t       callback,
        void         *arg,
        void         *buf,
        na_size_t     buf_size,
        na_addr_t     source,
        na_tag_t      tag,
        na_op_id_t   *op_id
        );

NA_EXPORT na_return_t
NA_Mem_handle_create(
        na_class_t      *na_class,
        void            *buf,
        na_size_t        buf_size,
        unsigned long    flags,
        na_mem_handle_t *mem_handle
        );

NA_EXPORT na_return_t
NA_Mem_handle_create_segments(
        na_class_t        *na_class,
        struct na_segment *segments,
        na_size_t          segment_count,
        unsigned long      flags,
        na_mem_handle_t   *mem_handle
        );

NA_EXPORT na_return_t
NA_Mem_handle_free(
        na_class_t      *na_class,
        na_mem_handle_t  mem_handle
        );

NA_EXPORT na_return_t
NA_Mem_register(
        na_class_t      *na_class,
        na_mem_handle_t  mem_handle
        );

NA_EXPORT na_return_t
NA_Mem_deregister(
        na_class_t      *na_class,
        na_mem_handle_t  mem_handle
        );

NA_EXPORT na_size_t
NA_Mem_handle_get_serialize_size(
        na_class_t      *na_class,
        na_mem_handle_t  mem_handle
        ) NA_WARN_UNUSED_RESULT;

NA_EXPORT na_return_t
NA_Mem_handle_serialize(
        na_class_t      *na_class,
        void            *buf,
        na_size_t        buf_size,
        na_mem_handle_t  mem_handle
        );

NA_EXPORT na_return_t
NA_Mem_handle_deserialize(
        na_class_t      *na_class,
        na_mem_handle_t *mem_handle,
        const void      *buf,
        na_size_t        buf_size
        );

NA_EXPORT na_return_t
NA_Put(
        na_class_t      *na_class,
        na_context_t    *context,
        na_cb_t          callback,
        void            *arg,
        na_mem_handle_t  local_mem_handle,
        na_offset_t      local_offset,
        na_mem_handle_t  remote_mem_handle,
        na_offset_t      remote_offset,
        na_size_t        data_size,
        na_addr_t        remote_addr,
        na_op_id_t      *op_id
        );

NA_EXPORT na_return_t
NA_Get(
        na_class_t      *na_class,
        na_context_t    *context,
        na_cb_t          callback,
        void            *arg,
        na_mem_handle_t  local_mem_handle,
        na_offset_t      local_offset,
        na_mem_handle_t  remote_mem_handle,
        na_offset_t      remote_offset,
        na_size_t        data_size,
        na_addr_t        remote_addr,
        na_op_id_t      *op_id
        );

NA_EXPORT na_return_t
NA_Progress(
        na_class_t   *na_class,
        na_context_t *context,
        unsigned int  timeout
        );

NA_EXPORT na_return_t
NA_Trigger(
        na_context_t *context,
        unsigned int  timeout,
        unsigned int  max_count,
        unsigned int *actual_count
        );

NA_EXPORT na_return_t
NA_Cancel(
        na_class_t   *na_class,
        na_context_t *context,
        na_op_id_t    op_id
        );

NA_EXPORT const char *
NA_Error_to_string(
        na_return_t errnum
        ) NA_WARN_UNUSED_RESULT;

#ifdef __cplusplus
}
#endif

#endif /* NA_H */