bake-bulk-client.h 5.61 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
/*
 * (C) 2016 The University of Chicago
 * 
 * See COPYRIGHT in top-level directory.
 */

#ifndef __BAKE_BULK_CLIENT_H
#define __BAKE_BULK_CLIENT_H

#include <stdint.h>
11
#include "margo.h"
12 13
#include "bake-bulk.h"

14 15 16 17
#ifdef __cplusplus
extern "C" {
#endif

18 19 20 21
/**
 * Obtain identifying information for a bake target through the provided
 * remote mercury address.
 *
22 23
 * @param [in] mid margo instance
 * @param [in] dest_addr destination Mercury address
24 25 26 27
 * @param [out] bti BAKE target identifier
 * @returns 0 on success, -1 on failure
 */
int bake_probe_instance(
28 29
    margo_instance_id mid,
    hg_addr_t dest_addr,
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
    bake_target_id_t *bti);
  
/**
 * Create a bounded-size bulk data region.  The resulting region can be
 * written using bulk write operations, and can be persisted (once writes are
 * complete) with a a bulk persist operation.  The region is not valid for
 * read access until persisted.
 *
 * @param [in] bti BAKE target identifier
 * @param [in] region_size size of region to be created
 * @param [out] rid identifier for new region
 * @returns 0 on success, -1 on failure
 */
int bake_bulk_create(
    bake_target_id_t bti,
    uint64_t region_size,
    bake_bulk_region_id_t *rid);
 
/**
 * Writes into a region that was previously created with bake_bulk_create().
 * Result is not guaranteed to be persistent until explicit
 * bake_bulk_persist() call.
 *
 * Results are undefined if multiple writers (from same process or different
 * processes) perform overlapping writes.
 *
 * @param [in] bti BAKE target identifier
 * @param [in] rid identifier for region
 * @param [in] region_offset offset into the target region to write
 * @param [in] buf local memory buffer to write
 * @param [in] buf_size size of local memory buffer to write
 * @returns 0 on success, -1 on failure
 */
int bake_bulk_write(
    bake_target_id_t bti,
    bake_bulk_region_id_t rid,
    uint64_t region_offset,
    void const *buf,
    uint64_t buf_size);
69 70

/**
Shane Snyder's avatar
Shane Snyder committed
71 72
 * Write data into a previously created BAKE region like bake_bulk_write(),
 * except the write is performed on behalf of some remote entity.
73
 *
Shane Snyder's avatar
Shane Snyder committed
74 75 76 77 78 79 80 81
 * @param [in] bti BAKE target identifier
 * @param [in] rid identifier for region
 * @param [in] region_offset offset into the target region to write
 * @param [in] remote_bulk bulk_handle for remote data region to write from
 * @param [in] remote_offset offset in the remote bulk handle to write from
 * @param [in] remote_addr address string of the remote target to write from
 * @param [in] size size to write from remote bulk handle
 * @returns 0 on success, -1 on failure
82 83 84 85 86 87 88
 */
int bake_bulk_proxy_write(
    bake_target_id_t bti,
    bake_bulk_region_id_t rid,
    uint64_t region_offset,
    hg_bulk_t remote_bulk,
    uint64_t remote_offset,
89
    const char* remote_addr,
90 91
    uint64_t size);

92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
/**
 * Persist a bulk region. The region is considered immutable at this point 
 * and reads may be performed on the region.
 *
 * @param [in] bti BAKE target identifier
 * @param [in] rid identifier for region
 * @returns 0 on success, -1 on failure
 */
int bake_bulk_persist(
    bake_target_id_t bti,
    bake_bulk_region_id_t rid);
  
/**
 * Check the size of an existing region. 
 *
 * @param [in] bti BAKE target identifier
 * @param [in] rid identifier for region
 * @param [out] size sizes of region
 * @returns 0 on success, -1 on failure
 */
int bake_bulk_get_size(
    bake_target_id_t bti,
    bake_bulk_region_id_t rid,
    uint64_t *region_size);

/**
 * Reads from a region that was previously persisted with bake_bulk_persist().
 *
 * NOTE: for now at least, this call does not support "short" reads.  It
 * either succeeds in reading the requested size or not.
 *
 * @param [in] bti BAKE target identifier
 * @param [in] rid region identifier
 * @param [in] region_offset offset into the target region to read from
 * @param [in] buf local memory buffer read into
 * @param [in] buf_size size of local memory buffer to read into
 * @returns 0 on success, -1 on failure
 */
int bake_bulk_read(
    bake_target_id_t bti,
    bake_bulk_region_id_t rid,
    uint64_t region_offset,
    void *buf,
    uint64_t buf_size);

137
/**
Shane Snyder's avatar
Shane Snyder committed
138 139
 * Read data from a previously persisted BAKE region like bake_bulk_read(),
 * except the read is performed on behalf of some remote entity.
140
 *
Shane Snyder's avatar
Shane Snyder committed
141 142 143 144 145 146 147 148
 * @param [in] bti BAKE target identifier
 * @param [in] rid identifier for region
 * @param [in] region_offset offset into the target region to write
 * @param [in] remote_bulk bulk_handle for remote data region to read to
 * @param [in] remote_offset offset in the remote bulk handle to read to
 * @param [in] remote_addr address string of the remote target to read to
 * @param [in] size size to read to remote bulk handle
 * @returns 0 on success, -1 on failure
149 150 151 152 153 154 155 156 157 158
 */
int bake_bulk_proxy_read(
    bake_target_id_t bti,
    bake_bulk_region_id_t rid,
    uint64_t region_offset,
    hg_bulk_t remote_bulk,
    uint64_t remote_offset,
    const char* remote_addr,
    uint64_t size);

159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
/**
 * Release local resources associated with access to a target; does not
 * modify the target in any way.
 *
 * @param [in] bti BAKE target_identifier
 */
void bake_release_instance(
    bake_target_id_t bti);

/**
 * Utility function to shut down a remote service
 *
 * @param [in] bti Bake target identifier
 * @returns 0 on success, -1 on fialure 
 */
int bake_shutdown_service(bake_target_id_t bti);

/* NOTE: code below is a copy of the bulk portion of the proposed BAKE API.
 * Commented out for now but leaving it in place for reference
 */

/**
 * Issue a no-op 
 *
 * @param [in] bti BAKE target identifier
 * @returns 0 on success, -1 on failure
 */
int bake_bulk_noop(
    bake_target_id_t bti);

189 190 191 192
#ifdef __cplusplus
}
#endif

193
#endif /* __BAKE_BULK__CLIENT_H */