ceph/examples/librados/hello_world.cc

   1 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
   2 // vim: ts=8 sw=2 smarttab
   3 /*
   4  * Ceph - scalable distributed file system
   5  *
   6  * This is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License version 2.1, as published by the Free Software
   9  * Foundation.  See file COPYING.
  10  * Copyright 2013 Inktank
  11  */
  12
  13 // install the librados-dev package to get this
  14 #include <rados/librados.hpp>
  15 #include <iostream>
  16 #include <string>
  17
  18 int main(int argc, const char **argv)
  19 {
  20   int ret = 0;
  21
  22   // we will use all of these below
  23   const char *pool_name = "hello_world_pool";
  24   std::string hello("hello world!");
  25   std::string object_name("hello_object");
  26   librados::IoCtx io_ctx;
  27
  28   // first, we create a Rados object and initialize it
  29   librados::Rados rados;
  30   {
  31     ret = rados.init("admin"); // just use the client.admin keyring
  32     if (ret < 0) { // let's handle any error that might have come back
  33       std::cerr << "couldn't initialize rados! error " << ret << std::endl;
  34       ret = EXIT_FAILURE;
  35       goto out;
  36     } else {
  37       std::cout << "we just set up a rados cluster object" << std::endl;
  38     }
  39   }
  40
  41   /*
  42    * Now we need to get the rados object its config info. It can
  43    * parse argv for us to find the id, monitors, etc, so let's just
  44    * use that.
  45    */
  46   {
  47     ret = rados.conf_parse_argv(argc, argv);
  48     if (ret < 0) {
  49       // This really can't happen, but we need to check to be a good citizen.
  50       std::cerr << "failed to parse config options! error " << ret << std::endl;
  51       ret = EXIT_FAILURE;
  52       goto out;
  53     } else {
  54       std::cout << "we just parsed our config options" << std::endl;
  55       // We also want to apply the config file if the user specified
  56       // one, and conf_parse_argv won't do that for us.
  57       for (int i = 0; i < argc; ++i) {
  58         if ((strcmp(argv[i], "-c") == 0) || (strcmp(argv[i], "--conf") == 0)) {
  59           ret = rados.conf_read_file(argv[i+1]);
  60           if (ret < 0) {
  61             // This could fail if the config file is malformed, but it'd be hard.
  62             std::cerr << "failed to parse config file " << argv[i+1]
  63                       << "! error" << ret << std::endl;
  64             ret = EXIT_FAILURE;
  65             goto out;
  66           }
  67           break;
  68         }
  69       }
  70     }
  71   }
  72
  73   /*
  74    * next, we actually connect to the cluster
  75    */
  76   {
  77     ret = rados.connect();
  78     if (ret < 0) {
  79       std::cerr << "couldn't connect to cluster! error " << ret << std::endl;
  80       ret = EXIT_FAILURE;
  81       goto out;
  82     } else {
  83       std::cout << "we just connected to the rados cluster" << std::endl;
  84     }
  85   }
  86
  87   /*
  88    * let's create our own pool instead of scribbling over real data.
  89    * Note that this command creates pools with default PG counts specified
  90    * by the monitors, which may not be appropriate for real use -- it's fine
  91    * for testing, though.
  92    */
  93   {
  94     ret = rados.pool_create(pool_name);
  95     if (ret < 0) {
  96       std::cerr << "couldn't create pool! error " << ret << std::endl;
  97       return EXIT_FAILURE;
  98     } else {
  99       std::cout << "we just created a new pool named " << pool_name << std::endl;
 100     }
 101   }
 102
 103   /*
 104    * create an "IoCtx" which is used to do IO to a pool
 105    */
 106   {
 107     ret = rados.ioctx_create(pool_name, io_ctx);
 108     if (ret < 0) {
 109       std::cerr << "couldn't set up ioctx! error " << ret << std::endl;
 110       ret = EXIT_FAILURE;
 111       goto out;
 112     } else {
 113       std::cout << "we just created an ioctx for our pool" << std::endl;
 114     }
 115   }
 116
 117   /*
 118    * now let's do some IO to the pool! We'll write "hello world!" to a
 119    * new object.
 120    */
 121   {
 122     /*
 123      * "bufferlist"s are Ceph's native transfer type, and are carefully
 124      * designed to be efficient about copying. You can fill them
 125      * up from a lot of different data types, but strings or c strings
 126      * are often convenient. Just make sure not to deallocate the memory
 127      * until the bufferlist goes out of scope and any requests using it
 128      * have been finished!
 129      */
 130     librados::bufferlist bl;
 131     bl.append(hello);
 132
 133     /*
 134      * now that we have the data to write, let's send it to an object.
 135      * We'll use the synchronous interface for simplicity.
 136      */
 137     ret = io_ctx.write_full(object_name, bl);
 138     if (ret < 0) {
 139       std::cerr << "couldn't write object! error " << ret << std::endl;
 140       ret = EXIT_FAILURE;
 141       goto out;
 142     } else {
 143       std::cout << "we just wrote new object " << object_name
 144                 << ", with contents\n" << hello << std::endl;
 145     }
 146   }
 147
 148   /*
 149    * now let's read that object back! Just for fun, we'll do it using
 150    * async IO instead of synchronous. (This would be more useful if we
 151    * wanted to send off multiple reads at once; see
 152    * http://docs.ceph.com/docs/master/rados/api/librados/#asychronous-io )
 153    */
 154   {
 155     librados::bufferlist read_buf;
 156     int read_len = 4194304; // this is way more than we need
 157     // allocate the completion from librados
 158     librados::AioCompletion *read_completion = librados::Rados::aio_create_completion();
 159     // send off the request.
 160     ret = io_ctx.aio_read(object_name, read_completion, &read_buf, read_len, 0);
 161     if (ret < 0) {
 162       std::cerr << "couldn't start read object! error " << ret << std::endl;
 163       ret = EXIT_FAILURE;
 164       goto out;
 165     }
 166     // wait for the request to complete, and check that it succeeded.
 167     read_completion->wait_for_complete();
 168     ret = read_completion->get_return_value();
 169     if (ret < 0) {
 170       std::cerr << "couldn't read object! error " << ret << std::endl;
 171       ret = EXIT_FAILURE;
 172       goto out;
 173     } else {
 174       std::cout << "we read our object " << object_name
 175           << ", and got back " << ret << " bytes with contents\n";
 176       std::string read_string;
 177       read_buf.copy(0, ret, read_string);
 178       std::cout << read_string << std::endl;
 179     }
 180   }
 181
 182   /*
 183    * We can also use xattrs that go alongside the object.
 184    */
 185   {
 186     librados::bufferlist version_bl;
 187     version_bl.append('1');
 188     ret = io_ctx.setxattr(object_name, "version", version_bl);
 189     if (ret < 0) {
 190       std::cerr << "failed to set xattr version entry! error "
 191                 << ret << std::endl;
 192       ret = EXIT_FAILURE;
 193       goto out;
 194     } else {
 195       std::cout << "we set the xattr 'version' on our object!" << std::endl;
 196     }
 197   }
 198
 199   /*
 200    * And if we want to be really cool, we can do multiple things in a single
 201    * atomic operation. For instance, we can update the contents of our object
 202    * and set the version at the same time.
 203    */
 204   {
 205     librados::bufferlist bl;
 206     bl.append(hello);
 207     bl.append("v2");
 208     librados::ObjectWriteOperation write_op;
 209     write_op.write_full(bl);
 210     librados::bufferlist version_bl;
 211     version_bl.append('2');
 212     write_op.setxattr("version", version_bl);
 213     ret = io_ctx.operate(object_name, &write_op);
 214     if (ret < 0) {
 215       std::cerr << "failed to do compound write! error " << ret << std::endl;
 216       ret = EXIT_FAILURE;
 217       goto out;
 218     } else {
 219       std::cout << "we overwrote our object " << object_name
 220                 << " with contents\n" << bl.c_str() << std::endl;
 221     }
 222   }
 223
 224   /*
 225    * And to be even cooler, we can make sure that the object looks the
 226    * way we expect before doing the write! Notice how this attempt fails
 227    * because the xattr differs.
 228    */
 229   {
 230     librados::ObjectWriteOperation failed_write_op;
 231     librados::bufferlist bl;
 232     bl.append(hello);
 233     bl.append("v2");
 234     librados::ObjectWriteOperation write_op;
 235     write_op.write_full(bl);
 236     librados::bufferlist version_bl;
 237     version_bl.append('2');
 238     librados::bufferlist old_version_bl;
 239     old_version_bl.append('1');
 240     failed_write_op.cmpxattr("version", LIBRADOS_CMPXATTR_OP_EQ, old_version_bl);
 241     failed_write_op.write_full(bl);
 242     failed_write_op.setxattr("version", version_bl);
 243     ret = io_ctx.operate(object_name, &failed_write_op);
 244     if (ret < 0) {
 245       std::cout << "we just failed a write because the xattr wasn't as specified"
 246                 << std::endl;
 247     } else {
 248       std::cerr << "we succeeded on writing despite an xattr comparison mismatch!"
 249                 << std::endl;
 250       ret = EXIT_FAILURE;
 251       goto out;
 252     }
 253
 254     /*
 255      * Now let's do the update with the correct xattr values so it
 256      * actually goes through
 257      */
 258     bl.clear();
 259     bl.append(hello);
 260     bl.append("v3");
 261     old_version_bl.clear();
 262     old_version_bl.append('2');
 263     version_bl.clear();
 264     version_bl.append('3');
 265     librados::ObjectWriteOperation update_op;
 266     update_op.cmpxattr("version", LIBRADOS_CMPXATTR_OP_EQ, old_version_bl);
 267     update_op.write_full(bl);
 268     update_op.setxattr("version", version_bl);
 269     ret = io_ctx.operate(object_name, &update_op);
 270     if (ret < 0) {
 271       std::cerr << "failed to do a compound write update! error " << ret
 272                 << std::endl;
 273       ret = EXIT_FAILURE;
 274       goto out;
 275     } else {
 276       std::cout << "we overwrote our object " << object_name
 277                 << " following an xattr test with contents\n" << bl.c_str()
 278                 << std::endl;
 279     }
 280   }
 281
 282   ret = EXIT_SUCCESS;
 283   out:
 284   /*
 285    * And now we're done, so let's remove our pool and then
 286    * shut down the connection gracefully.
 287    */
 288   int delete_ret = rados.pool_delete(pool_name);
 289   if (delete_ret < 0) {
 290     // be careful not to
 291     std::cerr << "We failed to delete our test pool!" << std::endl;
 292     ret = EXIT_FAILURE;
 293   }
 294
 295   rados.shutdown();
 296
 297   return ret;
 298 }