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 */