bake-client.h 10.8 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
 * @param [in] bti BAKE target identifier
 * @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(
210 211 212 213 214
        bake_provider_handle_t provider,
        bake_target_id_t bti,
        void const *buf,
        uint64_t buf_size,
        bake_region_id_t *rid);
215

216 217
/**
 *
218
 * @param [in] provider provider handle
219 220 221 222 223 224 225 226 227
 * @param [in] bti BAKE target identifier
 * @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(
228 229 230 231 232 233 234
        bake_provider_handle_t provider,
        bake_target_id_t bti,
        hg_bulk_t remote_bulk,
        uint64_t remote_offset,
        const char* remote_addr,
        uint64_t size,
        bake_region_id_t *rid);
235

236
/**
237
 * Checks the size of an existing BAKE region. 
238
 *
239
 * @param [in] provider provider handle
240
 * @param [in] rid identifier for region
241
 * @param [out] size size of region
242 243
 * @returns 0 on success, -1 on failure
 */
244
int bake_get_size(
245 246 247
        bake_provider_handle_t provider,
        bake_region_id_t rid,
        uint64_t *size);
248

249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273
/**
 * Gets the raw pointer of an existing BAKE region.
 * This pointer is valid in the address space of the
 * targeted BAKE provider. This function is meant to
 * be used when the client is co-located with the
 * BAKE provider and lives in the same address space
 * (e.g. active storage scenarios where we want to
 * access a piece of data without making a copy).
 * This function will return an error if the caller
 * is not running at the same address as the provider.
 *
 * Note that if the data pointed to is modified by the
 * client, the client will need to call bake_persist
 * to make the provider persist the changes.
 *
 * @param [in] provider provider handle
 * @param [in] rid identifier for region
 * @param [out] ptr pointer to the address of the data
 * @returns 0 on success, -1 on failure
 */
int bake_get_data(
        bake_provider_handle_t provider,
        bake_region_id_t rid,
        void** ptr);

274
/**
275
 * Reads from a BAKE region that was previously persisted with bake_persist().
276 277 278 279
 *
 * NOTE: for now at least, this call does not support "short" reads.  It
 * either succeeds in reading the requested size or not.
 *
280
 * @param [in] provider provider handle
281 282 283 284 285 286
 * @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
 */
287
int bake_read(
288 289 290 291 292
        bake_provider_handle_t provider,
        bake_region_id_t rid,
        uint64_t region_offset,
        void *buf,
        uint64_t buf_size);
293

294
/**
295
 * Reads data from a previously persisted BAKE region like bake_read(),
Shane Snyder's avatar
Shane Snyder committed
296
 * except the read is performed on behalf of some remote entity.
297
 *
298
 * @param [in] provider provider handle
Shane Snyder's avatar
Shane Snyder committed
299 300 301 302 303 304 305
 * @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
306
 */
307
int bake_proxy_read(
308 309 310 311 312 313 314
        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);
315 316

/**
317 318 319 320 321 322
 * 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 
323
 */
324
int bake_shutdown_service(
Shane Snyder's avatar
Shane Snyder committed
325 326
        bake_client_t client,
        hg_addr_t addr);
327 328

/**
329
 * Issues a BAKE no-op operation.
330
 *
331
 * @param [in] provider provider handle
332 333
 * @returns 0 on success, -1 on failure
 */
334
int bake_noop(bake_provider_handle_t provider);
335

Shane Snyder's avatar
Shane Snyder committed
336 337 338 339 340 341 342
/**
 * Removes a previously persisted BAKE region and frees its associated memory.
 */
int bake_remove(
        bake_provider_handle_t provider,
        bake_region_id_t rid);

343 344 345 346
#ifdef __cplusplus
}
#endif

347
#endif /* __BAKE_CLIENT_H */