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

7 8
#ifndef __BAKE_CLIENT_H
#define __BAKE_CLIENT_H
9 10

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

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

18
#define BAKE_CLIENT_NULL ((bake_client_t)NULL)
19
#define BAKE_PROVIDER_HANDLE_NULL ((bake_provider_handle_t)NULL)
20 21

typedef struct bake_client* bake_client_t;
22
typedef struct bake_provider_handle* bake_provider_handle_t;
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48

/**
 * Creates a BAKE client attached to the given margo instance.
 * This will effectively register the RPC needed by BAKE into
 * the margo instance. The client must be freed with
 * bake_client_finalize.
 *
 * @param[in] mid margo instance
 * @param[out] client resulting bake client object
 *
 * @return 0 on success, -1 on failure
 */
int bake_client_init(margo_instance_id mid, bake_client_t* client);

/**
 * Finalizes a BAKE client.
 * WARNING: This function must not be called after Margo has been
 * finalized. If you need to finalize a BAKE client when Margo is
 * finalized, use margo_push_finalize_callback.
 *
 * @param client BAKE client to destroy
 *
 * @return 0 on success, -1 on failure
 */
int bake_client_finalize(bake_client_t client);

49 50 51 52 53
/**
 * Creates a provider handle to point to a particular BAKE provider.
 *
 * @param client client managing the provider handle
 * @param addr address of the provider
54
 * @param provider_id id of the provider
55 56 57 58
 * @param handle resulting handle
 *
 * @return 0 on success, -1 on failure
 */
59 60 61
int bake_provider_handle_create(
        bake_client_t client,
        hg_addr_t addr,
62
        uint16_t provider_id,
63 64
        bake_provider_handle_t* handle);

65 66 67 68 69 70 71
/**
 * Increment the reference counter of the provider handle
 *
 * @param handle provider handle
 *
 * @return 0 on success, -1 on failure
 */
72 73
int bake_provider_handle_ref_incr(bake_provider_handle_t handle);

74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
/**
 * Get the limit (in bytes) bellow which this provider handle will use
 * eager mode (i.e. packing data into the RPC instead of using RDMA). 
 *
 * @param[in] handle provider handle
 * @param[out] limit limit
 *
 * @return 0 on success, -1 on failure
 */
int bake_provider_handle_get_eager_limit(bake_provider_handle_t handle, uint64_t* limit);

/**
 * Set the limit (in bytes) bellow which this provider handle will use
 * eager mode (i.e. packing data into the RPC instead of using RDMA).
 *
 * @param[in] handle provider handle
 * @param[in] limit limit
 *
 * @return 0 on success, -1 on failure
 */
int bake_provider_handle_set_eager_limit(bake_provider_handle_t handle, uint64_t limit);

96 97 98 99 100 101 102 103 104
/**
 * Decrement the reference counter of the provider handle,
 * effectively freeing the provider handle when the reference count
 * is down to 0.
 *
 * @param handle provider handle
 *
 * @return 0 on success, -1 on failure
 */
105 106
int bake_provider_handle_release(bake_provider_handle_t handle);

107
/**
108 109 110
 * Obtains available BAKE targets from a give provider.
 * If bake_target_id_t is NULL, max_targets is ignored and the
 * function returns the number of targets available in num_targets.
111
 *
112 113 114 115
 * @param [in] provider provider handle
 * @param [in] max_targets maximum number of targets to retrieve
 * @param [out] bti array of BAKE target identifiers with enough space for max_targets
 * @param [out] num_targets number of targets returned (at most max_targets)
116 117
 * @returns 0 on success, -1 on failure
 */
118 119 120 121 122
int bake_probe(
        bake_provider_handle_t provider,
        uint64_t max_targets,
        bake_target_id_t* bti,
        uint64_t* num_targets);
123 124
  
/**
125
 * Creates a bounded-size BAKE data region. The resulting region can be
126 127 128
 * written using BAKE write operations, and can be persisted (once writes
 * are complete) with a a BAKE persist operation.  The region is not valid
 * for read access until persisted.
129
 *
130
 * @param [in] provider provider handle
131 132 133 134 135
 * @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
 */
136
int bake_create(
137 138 139 140
        bake_provider_handle_t provider,
        bake_target_id_t bti,
        uint64_t region_size,
        bake_region_id_t *rid);
141 142
 
/**
143
 * Writes into a BAKE region that was previously created with bake_create().
144
 * Result is not guaranteed to be persistent until explicit
145
 * bake_persist() call.
146 147 148 149
 *
 * Results are undefined if multiple writers (from same process or different
 * processes) perform overlapping writes.
 *
150
 * @param [in] provider provider handle
151 152 153 154 155 156
 * @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
 */
157
int bake_write(
158 159 160 161 162
        bake_provider_handle_t provider,
        bake_region_id_t rid,
        uint64_t region_offset,
        void const *buf,
        uint64_t buf_size);
163 164

/**
165
 * Writes data into a previously created BAKE region like bake_write(),
Shane Snyder's avatar
Shane Snyder committed
166
 * except the write is performed on behalf of some remote entity.
167
 *
168
 * @param [in] provider provider handle
Shane Snyder's avatar
Shane Snyder committed
169 170 171 172 173 174 175
 * @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
176
 */
177
int bake_proxy_write(
178 179 180 181 182 183 184
        bake_provider_handle_t provider,
        bake_region_id_t rid,
        uint64_t region_offset,
        hg_bulk_t remote_bulk,
        uint64_t remote_offset,
        const char* remote_addr,
        uint64_t size);
185

186
/**
187
 * Persists a BAKE region. The region is considered immutable at this point 
188 189
 * and reads may be performed on the region.
 *
190
 * @param [in] provider provider handle
191 192 193
 * @param [in] rid identifier for region
 * @returns 0 on success, -1 on failure
 */
194
int bake_persist(
195 196
        bake_provider_handle_t provider,
        bake_region_id_t rid);
197

198 199 200 201
/**
 * Creates a bounded-size BAKE region, writes data into it, and persists
 * the reason all in one call/RPC (and thus 1 RTT).
 *
202
 * @param [in] provider provider handle
203 204 205 206 207 208 209 210 211
 * @param [in] bti BAKE target identifier
 * @param [in] region_size size of region to be created
 * @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
 * @param [out] rid identifier for new region
 * @returns 0 on success, -1 on failure
 */
int bake_create_write_persist(
212 213 214 215 216 217 218
        bake_provider_handle_t provider,
        bake_target_id_t bti,
        uint64_t region_size,
        uint64_t region_offset,
        void const *buf,
        uint64_t buf_size,
        bake_region_id_t *rid);
219

220 221
/**
 *
222
 * @param [in] provider provider handle
223 224 225 226 227 228 229 230 231 232 233
 * @param [in] bti BAKE target identifier
 * @param [in] region_size size of region to be created
 * @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
 * @param [out] rid identifier for new region
 * @returns 0 on success, -1 on failure
 */
int bake_create_write_persist_proxy(
234 235 236 237 238 239 240 241 242
        bake_provider_handle_t provider,
        bake_target_id_t bti,
        uint64_t region_size,
        uint64_t region_offset,
        hg_bulk_t remote_bulk,
        uint64_t remote_offset,
        const char* remote_addr,
        uint64_t size,
        bake_region_id_t *rid);
243

244
/**
245
 * Checks the size of an existing BAKE region. 
246
 *
247
 * @param [in] provider provider handle
248
 * @param [in] rid identifier for region
249
 * @param [out] size size of region
250 251
 * @returns 0 on success, -1 on failure
 */
252
int bake_get_size(
253 254 255
        bake_provider_handle_t provider,
        bake_region_id_t rid,
        uint64_t *size);
256 257

/**
258
 * Reads from a BAKE region that was previously persisted with bake_persist().
259 260 261 262
 *
 * NOTE: for now at least, this call does not support "short" reads.  It
 * either succeeds in reading the requested size or not.
 *
263
 * @param [in] provider provider handle
264 265 266 267 268 269
 * @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
 */
270
int bake_read(
271 272 273 274 275
        bake_provider_handle_t provider,
        bake_region_id_t rid,
        uint64_t region_offset,
        void *buf,
        uint64_t buf_size);
276

277
/**
278
 * Reads data from a previously persisted BAKE region like bake_read(),
Shane Snyder's avatar
Shane Snyder committed
279
 * except the read is performed on behalf of some remote entity.
280
 *
281
 * @param [in] provider provider handle
Shane Snyder's avatar
Shane Snyder committed
282 283 284 285 286 287 288
 * @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
289
 */
290
int bake_proxy_read(
291 292 293 294 295 296 297
        bake_provider_handle_t provider,
        bake_region_id_t rid,
        uint64_t region_offset,
        hg_bulk_t remote_bulk,
        uint64_t remote_offset,
        const char* remote_addr,
        uint64_t size);
298 299

/**
300 301 302 303 304 305
 * Shuts down a remote BAKE service (given an address).
 * This will shutdown all the providers on the target address.
 * 
 * @param [in] client BAKE client
 * @param [in] addr address of the server 
 * @returns 0 on success, -1 on failure 
306
 */
307
int bake_shutdown_service(
Shane Snyder's avatar
Shane Snyder committed
308 309
        bake_client_t client,
        hg_addr_t addr);
310 311

/**
312
 * Issues a BAKE no-op operation.
313
 *
314
 * @param [in] provider provider handle
315 316
 * @returns 0 on success, -1 on failure
 */
317
int bake_noop(bake_provider_handle_t provider);
318

Shane Snyder's avatar
Shane Snyder committed
319 320 321 322 323 324 325
/**
 * Removes a previously persisted BAKE region and frees its associated memory.
 */
int bake_remove(
        bake_provider_handle_t provider,
        bake_region_id_t rid);

326 327 328 329
#ifdef __cplusplus
}
#endif

330
#endif /* __BAKE_CLIENT_H */