mobject-client.h 13.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 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 49 50 51 52 53 54 55 56 57 58 59 60
/*
 * (C) 2018 The University of Chicago
 * 
 * See COPYRIGHT in top-level directory.
 */

#ifndef __MOBJECT_CLIENT_H
#define __MOBJECT_CLIENT_H

#include <stdint.h>
#include <margo.h>

#ifdef __cplusplus
extern "C" {
#endif

    typedef struct mobject_client* mobject_client_t;
    typedef struct mobject_provider_handle* mobject_provider_handle_t;
    typedef struct mobject_store_write_op *mobject_store_write_op_t;
    typedef struct mobject_store_read_op *mobject_store_read_op_t;
    typedef struct mobject_store_omap_iter *mobject_store_omap_iter_t;
    typedef struct mobject_store_completion* mobject_store_completion_t;
    typedef struct mobject_request* mobject_request_t;

#define MOBJECT_CLIENT_NULL          ((mobject_client_t)NULL)
#define MOBJECT_PROVIDER_HANDLE_NULL ((mobject_provider_handle_t)NULL)
#define MOBJECT_WRITE_OP_NULL        ((mobject_store_write_op_t)NULL)
#define MOBJECT_READ_OP_NULL         ((mobject_store_read_op_t)NULL)
#define MOBJECT_REQUEST_NULL         ((mobject_request_t)NULL)

    /**
     * Creates a Mobject 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
     * mobject_client_finalize.
     *
     * @param[in] mid margo instance
     * @param[out] client resulting mobject client object
     *
     * @return 0 on success, -1 on failure
     */
    int mobject_client_init(margo_instance_id mid, mobject_client_t* client);

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

    /**
     * Creates a provider handle to point to a particular Mobject provider.
     *
     * @param client client managing the provider handle
     * @param addr address of the provider
Matthieu Dorier's avatar
Matthieu Dorier committed
61
     * @param provider_id multiplex id of the provider
62 63 64 65 66 67 68
     * @param handle resulting handle
     *
     * @return 0 on success, -1 on failure
     */
    int mobject_provider_handle_create(
            mobject_client_t client,
            hg_addr_t addr,
Matthieu Dorier's avatar
Matthieu Dorier committed
69
            uint16_t provider_id,
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 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 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 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 189 190 191 192 193 194 195 196
            mobject_provider_handle_t* handle);

    /**
     * Increment the reference counter of the provider handle
     *
     * @param handle provider handle
     *
     * @return 0 on success, -1 on failure
     */
    int mobject_provider_handle_ref_incr(mobject_provider_handle_t handle);

    /**
     * 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
     */
    int mobject_provider_handle_release(mobject_provider_handle_t handle);

    int mobject_shutdown(mobject_client_t client, hg_addr_t addr);

    /**
     * Create a new mobject_store_write_op_t write operation.
     * This will store all actions to be performed atomically.
     * You must call mobject_store_release_write_op when you are
     * finished with it.
     *
     * @returns non-NULL on success, NULL on memory allocation error.
     */
    mobject_store_write_op_t mobject_create_write_op(void);

    /**
     * Free a mobject_store_write_op_t, must be called when you're done with it.
     * @param write_op operation to deallocate
     */
    void mobject_release_write_op(mobject_store_write_op_t write_op);

    /**
     * Create the object
     * @param write_op operation to add this action to
     * @param exclusive set to either LIBMOBJECT_CREATE_EXCLUSIVE or
     * LIBMOBJECT_CREATE_IDEMPOTENT
     * will error if the object already exists.
     * @param category category string (DEPRECATED, HAS NO EFFECT)
     */
    void mobject_write_op_create(
            mobject_store_write_op_t write_op,
            int exclusive,
            const char* category);

    /**
     * Write to offset
     * @param write_op operation to add this action to
     * @param offset offset to write to
     * @param buffer bytes to write
     * @param len length of buffer
     */
    void mobject_write_op_write(
            mobject_store_write_op_t write_op,
            const char *buffer,
            uint64_t offset,
            size_t len);

    /**
     * Write whole object, atomically replacing it.
     * @param write_op operation to add this action to
     * @param buffer bytes to write
     * @param len length of buffer
     */
    void mobject_write_op_write_full(
            mobject_store_write_op_t write_op,
            const char *buffer,
            size_t len);

    /**
     * Write the same buffer multiple times
     * @param write_op operation to add this action to
     * @param buffer bytes to write
     * @param data_len length of buffer
     * @param write_len total number of bytes to write, as a multiple of @data_len
     * @param offset offset to write to
     */
    void mobject_write_op_write_same(
            mobject_store_write_op_t write_op,
            const char *buffer,
            uint64_t offset,
            size_t data_len,
            size_t write_len);

    /**
     * Append to end of object.
     * @param write_op operation to add this action to
     * @param buffer bytes to write
     * @param len length of buffer
     */
    void mobject_write_op_append(
            mobject_store_write_op_t write_op,
            const char *buffer,
            size_t len);

    /**
     * Remove object
     * @param write_op operation to add this action to
     */
    void mobject_write_op_remove(mobject_store_write_op_t write_op);

    /**
     * Truncate an object
     * @param write_op operation to add this action to
     * @param offset Offset to truncate to
     */
    void mobject_write_op_truncate(
            mobject_store_write_op_t write_op,
            uint64_t offset);

    /**
     * Zero part of an object
     * @param write_op operation to add this action to
     * @param offset Offset to zero
     * @param len length to zero
     */
    void mobject_write_op_zero(
            mobject_store_write_op_t write_op,
            uint64_t offset,
197
            size_t len);
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 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 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407

    /**
     * Set key/value pairs on an object
     *
     * @param write_op operation to add this action to
     * @param keys array of null-terminated char arrays representing keys to set
     * @param vals array of pointers to values to set
     * @param lens array of lengths corresponding to each value
     * @param num number of key/value pairs to set
     */
    void mobject_write_op_omap_set(
            mobject_store_write_op_t write_op,
            char const* const* keys,
            char const* const* vals,
            const size_t *lens,
            size_t num);

    /**
     * Remove key/value pairs from an object
     *
     * @param write_op operation to add this action to
     * @param keys array of null-terminated char arrays representing keys to remove
     * @param keys_len number of key/value pairs to remove
     */
    void mobject_write_op_omap_rm_keys(
            mobject_store_write_op_t write_op,
            char const* const* keys,
            size_t keys_len);

    /**
     * Perform a write operation synchronously
     * @param write_op operation to perform
     * @param pool_name the name of the pool in which to write 
     * @param oid the object id
     * @param mtime the time to set the mtime to, NULL for the current time
     * @param flags flags to apply to the entire operation (LIBMOBJECT_OPERATION_*)
     */
    int mobject_write_op_operate(
            mobject_provider_handle_t handle,
            mobject_store_write_op_t write_op,
            const char* pool_name,
            const char *oid,
            time_t *mtime,
            int flags);

    /**
     * Perform a write operation asynchronously
     * @param write_op operation to perform
     * @param pool_name the name of the pool in which to write 
     * @param oid the object id
     * @param mtime the time to set the mtime to, NULL for the current time
     * @param flags flags to apply to the entire operation (LIBMOBJECT_OPERATION_*)
     * @param req resulting request
     */
    int mobject_aio_write_op_operate(
            mobject_provider_handle_t handle,
            mobject_store_write_op_t write_op,
            const char* pool_name,
            const char *oid,
            time_t *mtime,
            int flags,
            mobject_request_t* req);

    /**
     * Create a new mobject_store_read_op_t write operation. This will store all
     * actions to be performed atomically. You must call
     * mobject_store_release_read_op when you are finished with it (after it
     * completes, or you decide not to send it in the first place).
     *
     * @returns non-NULL on success, NULL on memory allocation error.
     */
    mobject_store_read_op_t mobject_create_read_op(void);

    /**
     * Free a mobject_store_read_op_t, must be called when you're done with it.
     * @param read_op operation to deallocate, created with mobject_create_read_op
     */
    void mobject_release_read_op(mobject_store_read_op_t read_op);

    /**
     * Get object size and mtime
     * @param read_op operation to add this action to
     * @param psize where to store object size
     * @param pmtime where to store modification time
     * @param prval where to store the return value of this action
     */
    void mobject_read_op_stat(
            mobject_store_read_op_t read_op,
            uint64_t *psize,
            time_t *pmtime,
            int *prval);
    /**
     * Read bytes from offset into buffer.
     *
     * prlen will be filled with the number of bytes read if successful.
     * A short read can only occur if the read reaches the end of the
     * object.
     *
     * @param read_op operation to add this action to
     * @param offset offset to read from
     * @param len length of buffer
     * @param buffer where to put the data
     * @param bytes_read where to store the number of bytes read by this action
     * @param prval where to store the return value of this action
     */
    void mobject_read_op_read(
            mobject_store_read_op_t read_op,
            char *buffer,
            uint64_t offset,
            size_t len,
            size_t *bytes_read,
            int *prval);

    /**
     * Start iterating over keys on an object.
     *
     * They will be returned sorted by key, and the iterator
     * will fill in NULL for all values if specified.
     *
     * @param read_op operation to add this action to
     * @param start_after list keys starting after start_after
     * @param max_return list no more than max_return keys
     * @param iter where to store the iterator
     * @param prval where to store the return value from this action
     */
    void mobject_read_op_omap_get_keys(
            mobject_store_read_op_t read_op,
            const char *start_after,
            uint64_t max_return,
            mobject_store_omap_iter_t *iter,
            int *prval);

    /**
     * Start iterating over key/value pairs on an object.
     *
     * They will be returned sorted by key.
     *
     * @param read_op operation to add this action to
     * @param start_after list keys starting after start_after
     * @param filter_prefix list only keys beginning with filter_prefix
     * @param max_return list no more than max_return key/value pairs
     * @param iter where to store the iterator
     * @param prval where to store the return value from this action
     */
    void mobject_read_op_omap_get_vals(
            mobject_store_read_op_t read_op,
            const char *start_after,
            const char *filter_prefix,
            uint64_t max_return,
            mobject_store_omap_iter_t *iter,
            int *prval);

    /**
     * Start iterating over specific key/value pairs
     *
     * They will be returned sorted by key.
     *
     * @param read_op operation to add this action to
     * @param keys array of pointers to null-terminated keys to get
     * @param keys_len the number of strings in keys
     * @param iter where to store the iterator
     * @param prval where to store the return value from this action
     */
    void mobject_read_op_omap_get_vals_by_keys(
            mobject_store_read_op_t read_op,
            char const* const* keys,
            size_t keys_len,
            mobject_store_omap_iter_t *iter,
            int *prval);


    /**
     * Perform a read operation synchronously
     * @param read_op operation to perform
     * @param pool_name the pool that the object is in
     * @param oid the object id
     * @param flags flags to apply to the entire operation (LIBMOBJECT_OPERATION_*)
     */
    int mobject_read_op_operate(
            mobject_provider_handle_t handle,
            mobject_store_read_op_t read_op,
            const char *pool_name,
            const char *oid,
            int flags);

    /**
     * Perform a read operation asynchronously
     * @param read_op operation to perform
     * @param pool_name the pool that the object is in
     * @param completion what to do when operation has been attempted
     * @param oid the object id
     * @param flags flags to apply to the entire operation (LIBMOBJECT_OPERATION_*)
     */
    int mobject_aio_read_op_operate(
            mobject_provider_handle_t handle,
            mobject_store_read_op_t read_op,
            const char *pool_name,
            const char *oid,
            int flags,
            mobject_request_t* req);

    int mobject_aio_wait(mobject_request_t req, int* ret);

    int mobject_aio_test(mobject_request_t req, int* flag);

#ifdef __cplusplus
}
#endif

#endif /* __MOBJECT_CLIENT_H */