mt-libcouchbase 1.4.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.gitignore +22 -0
- data/.gitmodules +3 -0
- data/.rspec +1 -0
- data/.travis.yml +38 -0
- data/Gemfile +4 -0
- data/LICENSE +24 -0
- data/README.md +445 -0
- data/Rakefile +76 -0
- data/ext/README.md +6 -0
- data/ext/Rakefile +19 -0
- data/ext/libcouchbase/.gitignore +132 -0
- data/ext/libcouchbase/CMakeLists.txt +455 -0
- data/ext/libcouchbase/CONTRIBUTING.md +105 -0
- data/ext/libcouchbase/LICENSE +202 -0
- data/ext/libcouchbase/README.markdown +195 -0
- data/ext/libcouchbase/RELEASE_NOTES.markdown +3523 -0
- data/ext/libcouchbase/cmake/Modules/ConfigureDtrace.cmake +52 -0
- data/ext/libcouchbase/cmake/Modules/CopyPDB.cmake +42 -0
- data/ext/libcouchbase/cmake/Modules/DistScript.cmake +17 -0
- data/ext/libcouchbase/cmake/Modules/DownloadLcbDep.cmake +18 -0
- data/ext/libcouchbase/cmake/Modules/FindCouchbaseHdrHistogram.cmake +15 -0
- data/ext/libcouchbase/cmake/Modules/FindCouchbaseLibev.cmake +73 -0
- data/ext/libcouchbase/cmake/Modules/FindCouchbaseLibevent.cmake +54 -0
- data/ext/libcouchbase/cmake/Modules/FindCouchbaseLibuv.cmake +57 -0
- data/ext/libcouchbase/cmake/Modules/FindProfiler.cmake +16 -0
- data/ext/libcouchbase/cmake/Modules/GenerateConfigDotH.cmake +49 -0
- data/ext/libcouchbase/cmake/Modules/GetLibcouchbaseFlags.cmake +142 -0
- data/ext/libcouchbase/cmake/Modules/GetPlatformCCInfo.cmake +45 -0
- data/ext/libcouchbase/cmake/Modules/GetVersionInfo.cmake +70 -0
- data/ext/libcouchbase/cmake/config-cmake.h.in +80 -0
- data/ext/libcouchbase/cmake/configure +355 -0
- data/ext/libcouchbase/cmake/defs.mk.in +6 -0
- data/ext/libcouchbase/cmake/dtrace-instr-link.pl +51 -0
- data/ext/libcouchbase/cmake/libcouchbase.stp.in +829 -0
- data/ext/libcouchbase/cmake/source_files.cmake +104 -0
- data/ext/libcouchbase/contrib/cJSON/cJSON.c +1022 -0
- data/ext/libcouchbase/contrib/cJSON/cJSON.h +158 -0
- data/ext/libcouchbase/contrib/cbsasl/CMakeLists.txt +25 -0
- data/ext/libcouchbase/contrib/cbsasl/COPYING +202 -0
- data/ext/libcouchbase/contrib/cbsasl/include/cbsasl/cbsasl.h +259 -0
- data/ext/libcouchbase/contrib/cbsasl/src/client.c +419 -0
- data/ext/libcouchbase/contrib/cbsasl/src/common.c +50 -0
- data/ext/libcouchbase/contrib/cbsasl/src/cram-md5/hmac.c +67 -0
- data/ext/libcouchbase/contrib/cbsasl/src/cram-md5/hmac.h +33 -0
- data/ext/libcouchbase/contrib/cbsasl/src/cram-md5/md5.c +296 -0
- data/ext/libcouchbase/contrib/cbsasl/src/cram-md5/md5.h +45 -0
- data/ext/libcouchbase/contrib/cbsasl/src/hash.c +573 -0
- data/ext/libcouchbase/contrib/cbsasl/src/hash.h +15 -0
- data/ext/libcouchbase/contrib/cbsasl/src/scram-sha/scram_utils.c +500 -0
- data/ext/libcouchbase/contrib/cbsasl/src/scram-sha/scram_utils.h +99 -0
- data/ext/libcouchbase/contrib/cbsasl/src/util.h +31 -0
- data/ext/libcouchbase/contrib/cliopts/CMakeLists.txt +2 -0
- data/ext/libcouchbase/contrib/cliopts/cliopts.c +938 -0
- data/ext/libcouchbase/contrib/cliopts/cliopts.h +610 -0
- data/ext/libcouchbase/contrib/genhash/genhash.c +371 -0
- data/ext/libcouchbase/contrib/genhash/genhash.h +241 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/CHANGES +157 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/CMakeLists.txt +252 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/CONTRIBUTORS +37 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/LICENSE +28 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/MINIFY.sh +15 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/README +435 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/cmake/internal_utils.cmake +227 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest-death-test.h +294 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest-message.h +250 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest-param-test.h +1421 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest-param-test.h.pump +487 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest-printers.h +855 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest-spi.h +232 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest-test-part.h +179 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest-typed-test.h +259 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest.h +2291 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest_pred_impl.h +358 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/gtest_prod.h +58 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-death-test-internal.h +319 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-filepath.h +206 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-internal.h +1158 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-linked_ptr.h +233 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-param-util-generated.h +5143 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-param-util-generated.h.pump +301 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-param-util.h +619 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-port.h +1947 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-string.h +167 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-tuple.h +1012 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-tuple.h.pump +339 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-type-util.h +3331 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/include/gtest/internal/gtest-type-util.h.pump +297 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest-all.cc +48 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest-death-test.cc +1344 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest-filepath.cc +382 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest-internal-inl.h +1218 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest-port.cc +805 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest-printers.cc +363 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest-test-part.cc +110 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest-typed-test.cc +110 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest.cc +5015 -0
- data/ext/libcouchbase/contrib/gtest-1.7.0/src/gtest_main.cc +38 -0
- data/ext/libcouchbase/contrib/http_parser/LICENSE-MIT +23 -0
- data/ext/libcouchbase/contrib/http_parser/README.md +178 -0
- data/ext/libcouchbase/contrib/http_parser/http_parser.c +2060 -0
- data/ext/libcouchbase/contrib/http_parser/http_parser.h +321 -0
- data/ext/libcouchbase/contrib/jsonsl/LICENSE +20 -0
- data/ext/libcouchbase/contrib/jsonsl/jsonsl.c +1452 -0
- data/ext/libcouchbase/contrib/jsonsl/jsonsl.h +971 -0
- data/ext/libcouchbase/contrib/lcb-jsoncpp/CMakeLists.txt +6 -0
- data/ext/libcouchbase/contrib/lcb-jsoncpp/LICENSE +55 -0
- data/ext/libcouchbase/contrib/lcb-jsoncpp/lcb-jsoncpp-forwards.h +255 -0
- data/ext/libcouchbase/contrib/lcb-jsoncpp/lcb-jsoncpp.cpp +4893 -0
- data/ext/libcouchbase/contrib/lcb-jsoncpp/lcb-jsoncpp.h +1961 -0
- data/ext/libcouchbase/contrib/snappy/CMakeLists.txt +7 -0
- data/ext/libcouchbase/contrib/snappy/COPYING +28 -0
- data/ext/libcouchbase/contrib/snappy/snappy-c.cc +90 -0
- data/ext/libcouchbase/contrib/snappy/snappy-c.h +138 -0
- data/ext/libcouchbase/contrib/snappy/snappy-internal.h +150 -0
- data/ext/libcouchbase/contrib/snappy/snappy-lcb-msvc.h +5 -0
- data/ext/libcouchbase/contrib/snappy/snappy-sinksource.cc +75 -0
- data/ext/libcouchbase/contrib/snappy/snappy-sinksource.h +137 -0
- data/ext/libcouchbase/contrib/snappy/snappy-stubs-internal.cc +42 -0
- data/ext/libcouchbase/contrib/snappy/snappy-stubs-internal.h +491 -0
- data/ext/libcouchbase/contrib/snappy/snappy-stubs-public.h +100 -0
- data/ext/libcouchbase/contrib/snappy/snappy.cc +1312 -0
- data/ext/libcouchbase/contrib/snappy/snappy.h +184 -0
- data/ext/libcouchbase/contrib/win32-defs/iocpdefs.h +133 -0
- data/ext/libcouchbase/contrib/win32-defs/mingwdefs.h +4396 -0
- data/ext/libcouchbase/contrib/win32-defs/win_stdint.h +258 -0
- data/ext/libcouchbase/doc/Doxyfile +2495 -0
- data/ext/libcouchbase/doc/DoxygenLayout.xml +109 -0
- data/ext/libcouchbase/doc/Makefile +44 -0
- data/ext/libcouchbase/doc/apiattr.h +117 -0
- data/ext/libcouchbase/doc/cbc-n1qlback.markdown +88 -0
- data/ext/libcouchbase/doc/cbc-pillowfight.markdown +296 -0
- data/ext/libcouchbase/doc/cbc-subdoc.markdown +299 -0
- data/ext/libcouchbase/doc/cbc.markdown +763 -0
- data/ext/libcouchbase/doc/cbcrc.markdown +52 -0
- data/ext/libcouchbase/doc/common-additional-options.markdown +82 -0
- data/ext/libcouchbase/doc/common-options.markdown +71 -0
- data/ext/libcouchbase/doc/environment.h +93 -0
- data/ext/libcouchbase/doc/example/threads.c +77 -0
- data/ext/libcouchbase/doc/footer.html +22 -0
- data/ext/libcouchbase/doc/genman.sh +25 -0
- data/ext/libcouchbase/doc/header.html +52 -0
- data/ext/libcouchbase/doc/intro.h +130 -0
- data/ext/libcouchbase/doc/mainpage.h +136 -0
- data/ext/libcouchbase/doc/man/cbc-admin.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-bucket-create.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-bucket-delete.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-cat.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-connstr.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-cp.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-create.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-decr.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-flush.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-hash.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-incr.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-lock.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-mcflush.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-mcversion.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-n1ql.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-n1qlback.1 +198 -0
- data/ext/libcouchbase/doc/man/cbc-observe.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-pillowfight.1 +499 -0
- data/ext/libcouchbase/doc/man/cbc-ping.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-rm.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-role-list.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-stats.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-subdoc.1 +494 -0
- data/ext/libcouchbase/doc/man/cbc-unlock.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-user-delete.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-user-list.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-user-upsert.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-verbosity.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-version.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-view.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc-watch.1 +1 -0
- data/ext/libcouchbase/doc/man/cbc.1 +1035 -0
- data/ext/libcouchbase/doc/man/cbcrc.4 +71 -0
- data/ext/libcouchbase/doc/style.css +1162 -0
- data/ext/libcouchbase/example/CMakeLists.txt +52 -0
- data/ext/libcouchbase/example/README.markdown +47 -0
- data/ext/libcouchbase/example/analytics/.gitignore +1 -0
- data/ext/libcouchbase/example/analytics/analytics.c +158 -0
- data/ext/libcouchbase/example/analytics/build-queries.rb +34 -0
- data/ext/libcouchbase/example/analytics/cJSON.c +1 -0
- data/ext/libcouchbase/example/analytics/cJSON.h +1 -0
- data/ext/libcouchbase/example/analytics/queries/00-show-dataverse.json +5 -0
- data/ext/libcouchbase/example/analytics/queries/01-setup-dataset-breweries.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/02-setup-dataset-beers.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/03-initiate-shadow.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/04-list-datasets.json +7 -0
- data/ext/libcouchbase/example/analytics/queries/05-count-breweries.json +5 -0
- data/ext/libcouchbase/example/analytics/queries/06-first-brewery.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/07-key-based-lookup.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/08-exact-match-lookup.json +7 -0
- data/ext/libcouchbase/example/analytics/queries/09-exact-match-lookup-different-shape.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/10-other-query-filters.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/11-equijoin.json +9 -0
- data/ext/libcouchbase/example/analytics/queries/12-equijoin-select-star.json +10 -0
- data/ext/libcouchbase/example/analytics/queries/13-ansi-join.json +8 -0
- data/ext/libcouchbase/example/analytics/queries/14-join-select-values.json +8 -0
- data/ext/libcouchbase/example/analytics/queries/15-nested-outer-join.json +7 -0
- data/ext/libcouchbase/example/analytics/queries/16-theta-join.json +8 -0
- data/ext/libcouchbase/example/analytics/queries/17-existential-quantification.json +9 -0
- data/ext/libcouchbase/example/analytics/queries/18-universal-quantification.json +7 -0
- data/ext/libcouchbase/example/analytics/queries/19-simple-aggregation.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/20-simple-aggregation-unwrapped-value.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/21-simple-aggregation-explicit.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/22-grouping-and-aggregation.json +6 -0
- data/ext/libcouchbase/example/analytics/queries/23-grouping-and-aggregation-with-hint.json +7 -0
- data/ext/libcouchbase/example/analytics/queries/24-grouping-and-limits.json +7 -0
- data/ext/libcouchbase/example/analytics/queries/25-named-parameters.json +7 -0
- data/ext/libcouchbase/example/analytics/queries/26-positional-parameters.json +7 -0
- data/ext/libcouchbase/example/analytics/queries.h +113 -0
- data/ext/libcouchbase/example/crypto/.gitignore +2 -0
- data/ext/libcouchbase/example/crypto/Makefile +13 -0
- data/ext/libcouchbase/example/crypto/common_provider.c +26 -0
- data/ext/libcouchbase/example/crypto/common_provider.h +33 -0
- data/ext/libcouchbase/example/crypto/openssl_symmetric_decrypt.c +144 -0
- data/ext/libcouchbase/example/crypto/openssl_symmetric_encrypt.c +146 -0
- data/ext/libcouchbase/example/crypto/openssl_symmetric_provider.c +271 -0
- data/ext/libcouchbase/example/crypto/openssl_symmetric_provider.h +29 -0
- data/ext/libcouchbase/example/db/db.c +171 -0
- data/ext/libcouchbase/example/db/vb.c +227 -0
- data/ext/libcouchbase/example/fts/.gitignore +1 -0
- data/ext/libcouchbase/example/fts/build-queries.rb +33 -0
- data/ext/libcouchbase/example/fts/fts.c +142 -0
- data/ext/libcouchbase/example/fts/queries/00-simple-text-query.json +12 -0
- data/ext/libcouchbase/example/fts/queries/01-simple-text-query-on-non-default-index.json +9 -0
- data/ext/libcouchbase/example/fts/queries/02-simple-text-query-on-stored-field.json +13 -0
- data/ext/libcouchbase/example/fts/queries/03-match-query-with-facet.json +19 -0
- data/ext/libcouchbase/example/fts/queries/04-docid-query.json +11 -0
- data/ext/libcouchbase/example/fts/queries/05-unanalyzed-term-query-with-fuzziness-level-of-0.json +13 -0
- data/ext/libcouchbase/example/fts/queries/06-unanalyzed-term-query-with-fuzziness-level-of-2.json +14 -0
- data/ext/libcouchbase/example/fts/queries/07-match-phrase-query.json +13 -0
- data/ext/libcouchbase/example/fts/queries/08-phrase-query.json +16 -0
- data/ext/libcouchbase/example/fts/queries/09-query-string-query.json +9 -0
- data/ext/libcouchbase/example/fts/queries/10-conjunction-query.json +21 -0
- data/ext/libcouchbase/example/fts/queries/11-wild-card-query.json +13 -0
- data/ext/libcouchbase/example/fts/queries/12-numeric-range-query.json +11 -0
- data/ext/libcouchbase/example/fts/queries/13-regexp-query.json +13 -0
- data/ext/libcouchbase/example/fts/queries.h +61 -0
- data/ext/libcouchbase/example/instancepool/main.cc +112 -0
- data/ext/libcouchbase/example/instancepool/pool.cc +102 -0
- data/ext/libcouchbase/example/instancepool/pool.h +69 -0
- data/ext/libcouchbase/example/libeventdirect/main.c +222 -0
- data/ext/libcouchbase/example/mcc/mcc.cc +246 -0
- data/ext/libcouchbase/example/minimal/.gitignore +1 -0
- data/ext/libcouchbase/example/minimal/minimal.c +132 -0
- data/ext/libcouchbase/example/minimal/query.c +185 -0
- data/ext/libcouchbase/example/observe/durability.c +102 -0
- data/ext/libcouchbase/example/observe/observe.c +159 -0
- data/ext/libcouchbase/example/subdoc/subdoc-multi.cc +143 -0
- data/ext/libcouchbase/example/subdoc/subdoc-simple.cc +201 -0
- data/ext/libcouchbase/example/subdoc/subdoc-xattrs.c +286 -0
- data/ext/libcouchbase/example/tick/tick.c +119 -0
- data/ext/libcouchbase/example/tracing/.gitignore +2 -0
- data/ext/libcouchbase/example/tracing/Makefile +8 -0
- data/ext/libcouchbase/example/tracing/cJSON.c +1 -0
- data/ext/libcouchbase/example/tracing/cJSON.h +1 -0
- data/ext/libcouchbase/example/tracing/tracing.c +439 -0
- data/ext/libcouchbase/example/tracing/views.c +444 -0
- data/ext/libcouchbase/example/users/README +48 -0
- data/ext/libcouchbase/example/users/users.c +147 -0
- data/ext/libcouchbase/example/views/views-example.cc +83 -0
- data/ext/libcouchbase/include/libcouchbase/_cxxwrap.h +150 -0
- data/ext/libcouchbase/include/libcouchbase/api-legacy.h +1689 -0
- data/ext/libcouchbase/include/libcouchbase/api3.h +2 -0
- data/ext/libcouchbase/include/libcouchbase/assert.h +44 -0
- data/ext/libcouchbase/include/libcouchbase/auth.h +297 -0
- data/ext/libcouchbase/include/libcouchbase/cbft.h +151 -0
- data/ext/libcouchbase/include/libcouchbase/cntl-private.h +319 -0
- data/ext/libcouchbase/include/libcouchbase/cntl.h +1418 -0
- data/ext/libcouchbase/include/libcouchbase/configuration.h.in +29 -0
- data/ext/libcouchbase/include/libcouchbase/couchbase.h +4089 -0
- data/ext/libcouchbase/include/libcouchbase/crypto.h +306 -0
- data/ext/libcouchbase/include/libcouchbase/deprecated.h +312 -0
- data/ext/libcouchbase/include/libcouchbase/error.h +680 -0
- data/ext/libcouchbase/include/libcouchbase/http.h +1 -0
- data/ext/libcouchbase/include/libcouchbase/iops.h +1053 -0
- data/ext/libcouchbase/include/libcouchbase/ixmgmt.h +263 -0
- data/ext/libcouchbase/include/libcouchbase/kvbuf.h +137 -0
- data/ext/libcouchbase/include/libcouchbase/metrics.h +79 -0
- data/ext/libcouchbase/include/libcouchbase/n1ql.h +539 -0
- data/ext/libcouchbase/include/libcouchbase/pktfwd.h +270 -0
- data/ext/libcouchbase/include/libcouchbase/plugins/io/bsdio-inl.c +370 -0
- data/ext/libcouchbase/include/libcouchbase/plugins/io/wsaerr-inl.c +76 -0
- data/ext/libcouchbase/include/libcouchbase/plugins/io/wsaerr.h +199 -0
- data/ext/libcouchbase/include/libcouchbase/subdoc.h +347 -0
- data/ext/libcouchbase/include/libcouchbase/sysdefs.h +98 -0
- data/ext/libcouchbase/include/libcouchbase/tracing.h +437 -0
- data/ext/libcouchbase/include/libcouchbase/vbucket.h +680 -0
- data/ext/libcouchbase/include/libcouchbase/views.h +357 -0
- data/ext/libcouchbase/include/libcouchbase/visibility.h +66 -0
- data/ext/libcouchbase/include/memcached/COPYING +30 -0
- data/ext/libcouchbase/include/memcached/README +10 -0
- data/ext/libcouchbase/include/memcached/protocol_binary.h +885 -0
- data/ext/libcouchbase/packaging/README +7 -0
- data/ext/libcouchbase/packaging/abicheck/.gitignore +4 -0
- data/ext/libcouchbase/packaging/abicheck/Makefile +17 -0
- data/ext/libcouchbase/packaging/abicheck/README.md +27 -0
- data/ext/libcouchbase/packaging/abicheck/template.xml +3 -0
- data/ext/libcouchbase/packaging/deb/compat +1 -0
- data/ext/libcouchbase/packaging/deb/control +72 -0
- data/ext/libcouchbase/packaging/deb/copyright +10 -0
- data/ext/libcouchbase/packaging/deb/libcouchbase-dev.docs +3 -0
- data/ext/libcouchbase/packaging/deb/package.mk +31 -0
- data/ext/libcouchbase/packaging/deb/rules +46 -0
- data/ext/libcouchbase/packaging/deb/source/format +1 -0
- data/ext/libcouchbase/packaging/distinfo/README +1 -0
- data/ext/libcouchbase/packaging/distinfo/distinfo.cmake.in +4 -0
- data/ext/libcouchbase/packaging/dllversion.rc.in +39 -0
- data/ext/libcouchbase/packaging/libcouchbase.pc.in +10 -0
- data/ext/libcouchbase/packaging/nuget/libcouchbase.autopkg +76 -0
- data/ext/libcouchbase/packaging/parse-git-describe.pl +166 -0
- data/ext/libcouchbase/packaging/rpm/libcouchbase.spec.in +101 -0
- data/ext/libcouchbase/packaging/rpm/package.mk +40 -0
- data/ext/libcouchbase/plugins/io/iocp/CMakeLists.txt +9 -0
- data/ext/libcouchbase/plugins/io/iocp/iocp_iops.c +467 -0
- data/ext/libcouchbase/plugins/io/iocp/iocp_iops.h +217 -0
- data/ext/libcouchbase/plugins/io/iocp/iocp_loop.c +295 -0
- data/ext/libcouchbase/plugins/io/iocp/iocp_timer.c +79 -0
- data/ext/libcouchbase/plugins/io/iocp/iocp_util.c +229 -0
- data/ext/libcouchbase/plugins/io/libev/CMakeLists.txt +31 -0
- data/ext/libcouchbase/plugins/io/libev/libev_io_opts.h +66 -0
- data/ext/libcouchbase/plugins/io/libev/plugin-libev.c +289 -0
- data/ext/libcouchbase/plugins/io/libevent/CMakeLists.txt +31 -0
- data/ext/libcouchbase/plugins/io/libevent/libevent_io_opts.h +67 -0
- data/ext/libcouchbase/plugins/io/libevent/plugin-libevent.c +292 -0
- data/ext/libcouchbase/plugins/io/libuv/CMakeLists.txt +44 -0
- data/ext/libcouchbase/plugins/io/libuv/libuv_compat.h +218 -0
- data/ext/libcouchbase/plugins/io/libuv/libuv_io_opts.h +118 -0
- data/ext/libcouchbase/plugins/io/libuv/plugin-internal.h +155 -0
- data/ext/libcouchbase/plugins/io/libuv/plugin-libuv.c +709 -0
- data/ext/libcouchbase/plugins/io/select/CMakeLists.txt +13 -0
- data/ext/libcouchbase/plugins/io/select/plugin-select.c +451 -0
- data/ext/libcouchbase/plugins/io/select/select_io_opts.h +39 -0
- data/ext/libcouchbase/src/README.md +101 -0
- data/ext/libcouchbase/src/aspend.h +105 -0
- data/ext/libcouchbase/src/auth-priv.h +85 -0
- data/ext/libcouchbase/src/auth.cc +146 -0
- data/ext/libcouchbase/src/bootstrap.cc +263 -0
- data/ext/libcouchbase/src/bootstrap.h +149 -0
- data/ext/libcouchbase/src/bucketconfig/bc_cccp.cc +450 -0
- data/ext/libcouchbase/src/bucketconfig/bc_file.cc +281 -0
- data/ext/libcouchbase/src/bucketconfig/bc_http.cc +527 -0
- data/ext/libcouchbase/src/bucketconfig/bc_http.h +107 -0
- data/ext/libcouchbase/src/bucketconfig/bc_static.cc +150 -0
- data/ext/libcouchbase/src/bucketconfig/clconfig.h +700 -0
- data/ext/libcouchbase/src/bucketconfig/confmon.cc +403 -0
- data/ext/libcouchbase/src/callbacks.c +380 -0
- data/ext/libcouchbase/src/cbft.cc +253 -0
- data/ext/libcouchbase/src/cntl.cc +1057 -0
- data/ext/libcouchbase/src/config_static.h +176 -0
- data/ext/libcouchbase/src/connspec.cc +555 -0
- data/ext/libcouchbase/src/connspec.h +155 -0
- data/ext/libcouchbase/src/crypto.cc +399 -0
- data/ext/libcouchbase/src/ctx-log-inl.h +44 -0
- data/ext/libcouchbase/src/dns-srv.cc +146 -0
- data/ext/libcouchbase/src/dump.cc +103 -0
- data/ext/libcouchbase/src/errmap.cc +173 -0
- data/ext/libcouchbase/src/errmap.h +271 -0
- data/ext/libcouchbase/src/getconfig.cc +72 -0
- data/ext/libcouchbase/src/gethrtime.c +109 -0
- data/ext/libcouchbase/src/handler.cc +1101 -0
- data/ext/libcouchbase/src/hashtable.c +75 -0
- data/ext/libcouchbase/src/hdr_timings.c +92 -0
- data/ext/libcouchbase/src/hostlist.cc +293 -0
- data/ext/libcouchbase/src/hostlist.h +160 -0
- data/ext/libcouchbase/src/http/http-priv.h +326 -0
- data/ext/libcouchbase/src/http/http.cc +672 -0
- data/ext/libcouchbase/src/http/http.h +1 -0
- data/ext/libcouchbase/src/http/http_io.cc +316 -0
- data/ext/libcouchbase/src/instance.cc +917 -0
- data/ext/libcouchbase/src/internal.h +285 -0
- data/ext/libcouchbase/src/iofactory.c +575 -0
- data/ext/libcouchbase/src/jsparse/parser.cc +445 -0
- data/ext/libcouchbase/src/jsparse/parser.h +159 -0
- data/ext/libcouchbase/src/lcbht/lcbht.cc +177 -0
- data/ext/libcouchbase/src/lcbht/lcbht.h +210 -0
- data/ext/libcouchbase/src/lcbio/connect.cc +603 -0
- data/ext/libcouchbase/src/lcbio/connect.h +400 -0
- data/ext/libcouchbase/src/lcbio/ctx.c +658 -0
- data/ext/libcouchbase/src/lcbio/ctx.h +405 -0
- data/ext/libcouchbase/src/lcbio/iotable.c +290 -0
- data/ext/libcouchbase/src/lcbio/iotable.h +169 -0
- data/ext/libcouchbase/src/lcbio/ioutils.cc +356 -0
- data/ext/libcouchbase/src/lcbio/ioutils.h +144 -0
- data/ext/libcouchbase/src/lcbio/lcbio.h +51 -0
- data/ext/libcouchbase/src/lcbio/manager.cc +579 -0
- data/ext/libcouchbase/src/lcbio/manager.h +195 -0
- data/ext/libcouchbase/src/lcbio/protoctx.c +84 -0
- data/ext/libcouchbase/src/lcbio/rw-inl.h +137 -0
- data/ext/libcouchbase/src/lcbio/ssl.h +159 -0
- data/ext/libcouchbase/src/lcbio/timer-cxx.h +87 -0
- data/ext/libcouchbase/src/lcbio/timer-ng.h +179 -0
- data/ext/libcouchbase/src/lcbio/timer.c +132 -0
- data/ext/libcouchbase/src/legacy.c +431 -0
- data/ext/libcouchbase/src/list.c +144 -0
- data/ext/libcouchbase/src/list.h +127 -0
- data/ext/libcouchbase/src/logging.c +244 -0
- data/ext/libcouchbase/src/logging.h +88 -0
- data/ext/libcouchbase/src/mc/compress.cc +171 -0
- data/ext/libcouchbase/src/mc/compress.h +56 -0
- data/ext/libcouchbase/src/mc/forward.c +186 -0
- data/ext/libcouchbase/src/mc/forward.h +90 -0
- data/ext/libcouchbase/src/mc/iovcursor-inl.h +279 -0
- data/ext/libcouchbase/src/mc/iovcursor.h +66 -0
- data/ext/libcouchbase/src/mc/mcreq-flush-inl.h +115 -0
- data/ext/libcouchbase/src/mc/mcreq.c +983 -0
- data/ext/libcouchbase/src/mc/mcreq.h +1015 -0
- data/ext/libcouchbase/src/mcserver/mcserver.cc +1055 -0
- data/ext/libcouchbase/src/mcserver/mcserver.h +221 -0
- data/ext/libcouchbase/src/mcserver/negotiate.cc +757 -0
- data/ext/libcouchbase/src/mcserver/negotiate.h +128 -0
- data/ext/libcouchbase/src/mctx-helper.h +62 -0
- data/ext/libcouchbase/src/metrics.cc +132 -0
- data/ext/libcouchbase/src/n1ql/ixmgmt.cc +857 -0
- data/ext/libcouchbase/src/n1ql/n1ql-internal.h +22 -0
- data/ext/libcouchbase/src/n1ql/n1ql.cc +830 -0
- data/ext/libcouchbase/src/n1ql/params.cc +260 -0
- data/ext/libcouchbase/src/netbuf/netbuf-defs.h +89 -0
- data/ext/libcouchbase/src/netbuf/netbuf-mblock.h +235 -0
- data/ext/libcouchbase/src/netbuf/netbuf.c +929 -0
- data/ext/libcouchbase/src/netbuf/netbuf.h +452 -0
- data/ext/libcouchbase/src/newconfig.cc +365 -0
- data/ext/libcouchbase/src/nodeinfo.cc +184 -0
- data/ext/libcouchbase/src/operations/cbflush.cc +63 -0
- data/ext/libcouchbase/src/operations/counter.cc +117 -0
- data/ext/libcouchbase/src/operations/durability-cas.cc +251 -0
- data/ext/libcouchbase/src/operations/durability-seqno.cc +170 -0
- data/ext/libcouchbase/src/operations/durability.cc +668 -0
- data/ext/libcouchbase/src/operations/durability_internal.h +306 -0
- data/ext/libcouchbase/src/operations/get.cc +409 -0
- data/ext/libcouchbase/src/operations/observe-seqno.cc +94 -0
- data/ext/libcouchbase/src/operations/observe.cc +367 -0
- data/ext/libcouchbase/src/operations/ping.cc +496 -0
- data/ext/libcouchbase/src/operations/pktfwd.cc +86 -0
- data/ext/libcouchbase/src/operations/remove.cc +84 -0
- data/ext/libcouchbase/src/operations/stats.cc +459 -0
- data/ext/libcouchbase/src/operations/store.cc +358 -0
- data/ext/libcouchbase/src/operations/subdoc.cc +614 -0
- data/ext/libcouchbase/src/operations/touch.cc +84 -0
- data/ext/libcouchbase/src/packetutils.h +388 -0
- data/ext/libcouchbase/src/probes.d +182 -0
- data/ext/libcouchbase/src/rdb/bigalloc.c +225 -0
- data/ext/libcouchbase/src/rdb/bigalloc.h +73 -0
- data/ext/libcouchbase/src/rdb/chunkalloc.c +174 -0
- data/ext/libcouchbase/src/rdb/libcalloc.c +94 -0
- data/ext/libcouchbase/src/rdb/rope.c +419 -0
- data/ext/libcouchbase/src/rdb/rope.h +488 -0
- data/ext/libcouchbase/src/retrychk.cc +113 -0
- data/ext/libcouchbase/src/retryq.cc +458 -0
- data/ext/libcouchbase/src/retryq.h +170 -0
- data/ext/libcouchbase/src/ringbuffer.c +442 -0
- data/ext/libcouchbase/src/ringbuffer.h +100 -0
- data/ext/libcouchbase/src/rnd.cc +61 -0
- data/ext/libcouchbase/src/rnd.h +39 -0
- data/ext/libcouchbase/src/settings.c +125 -0
- data/ext/libcouchbase/src/settings.h +273 -0
- data/ext/libcouchbase/src/sllist-inl.h +197 -0
- data/ext/libcouchbase/src/sllist.h +76 -0
- data/ext/libcouchbase/src/ssl/CMakeLists.txt +11 -0
- data/ext/libcouchbase/src/ssl/ssl_c.c +442 -0
- data/ext/libcouchbase/src/ssl/ssl_common.c +478 -0
- data/ext/libcouchbase/src/ssl/ssl_e.c +421 -0
- data/ext/libcouchbase/src/ssl/ssl_iot_common.h +182 -0
- data/ext/libcouchbase/src/strcodecs/base64.c +307 -0
- data/ext/libcouchbase/src/strcodecs/strcodecs.h +302 -0
- data/ext/libcouchbase/src/timings.c +207 -0
- data/ext/libcouchbase/src/trace.h +117 -0
- data/ext/libcouchbase/src/tracing/span.cc +421 -0
- data/ext/libcouchbase/src/tracing/threshold_logging_tracer.cc +213 -0
- data/ext/libcouchbase/src/tracing/tracer.cc +53 -0
- data/ext/libcouchbase/src/tracing/tracing-internal.h +198 -0
- data/ext/libcouchbase/src/utilities.c +176 -0
- data/ext/libcouchbase/src/vbucket/CMakeLists.txt +2 -0
- data/ext/libcouchbase/src/vbucket/aliases.h +35 -0
- data/ext/libcouchbase/src/vbucket/crc32.h +83 -0
- data/ext/libcouchbase/src/vbucket/hash.h +30 -0
- data/ext/libcouchbase/src/vbucket/json-inl.h +112 -0
- data/ext/libcouchbase/src/vbucket/ketama.c +66 -0
- data/ext/libcouchbase/src/vbucket/rfc1321/global.h +32 -0
- data/ext/libcouchbase/src/vbucket/rfc1321/md5.h +35 -0
- data/ext/libcouchbase/src/vbucket/rfc1321/md5c-inl.h +335 -0
- data/ext/libcouchbase/src/vbucket/vbucket.c +1735 -0
- data/ext/libcouchbase/src/views/docreq.cc +213 -0
- data/ext/libcouchbase/src/views/docreq.h +94 -0
- data/ext/libcouchbase/src/views/viewreq.cc +381 -0
- data/ext/libcouchbase/src/views/viewreq.h +87 -0
- data/ext/libcouchbase/src/wait.cc +156 -0
- data/ext/libcouchbase/tests/CMakeLists.txt +149 -0
- data/ext/libcouchbase/tests/basic/t_base64.cc +109 -0
- data/ext/libcouchbase/tests/basic/t_ccbc103.cc +95 -0
- data/ext/libcouchbase/tests/basic/t_connstr.cc +456 -0
- data/ext/libcouchbase/tests/basic/t_creds.cc +96 -0
- data/ext/libcouchbase/tests/basic/t_ctlcodes.cc +92 -0
- data/ext/libcouchbase/tests/basic/t_host.cc +210 -0
- data/ext/libcouchbase/tests/basic/t_jsparse.cc +82 -0
- data/ext/libcouchbase/tests/basic/t_jsparse.h +589 -0
- data/ext/libcouchbase/tests/basic/t_list.cc +155 -0
- data/ext/libcouchbase/tests/basic/t_logger.cc +65 -0
- data/ext/libcouchbase/tests/basic/t_misc.cc +24 -0
- data/ext/libcouchbase/tests/basic/t_n1qlstrings.cc +17 -0
- data/ext/libcouchbase/tests/basic/t_netbuf.cc +446 -0
- data/ext/libcouchbase/tests/basic/t_packet.cc +215 -0
- data/ext/libcouchbase/tests/basic/t_ringbuffer.cc +278 -0
- data/ext/libcouchbase/tests/basic/t_scram.cc +514 -0
- data/ext/libcouchbase/tests/basic/t_slist.cc +429 -0
- data/ext/libcouchbase/tests/basic/t_strerror.cc +64 -0
- data/ext/libcouchbase/tests/basic/t_urlencode.cc +132 -0
- data/ext/libcouchbase/tests/check-all.cc +612 -0
- data/ext/libcouchbase/tests/htparse/t_basic.cc +173 -0
- data/ext/libcouchbase/tests/ioserver/connection.cc +166 -0
- data/ext/libcouchbase/tests/ioserver/future.cc +50 -0
- data/ext/libcouchbase/tests/ioserver/ioserver.cc +117 -0
- data/ext/libcouchbase/tests/ioserver/ioserver.h +478 -0
- data/ext/libcouchbase/tests/ioserver/socket.cc +88 -0
- data/ext/libcouchbase/tests/ioserver/ssl_connection.cc +145 -0
- data/ext/libcouchbase/tests/ioserver/threads-pthreads.cc +119 -0
- data/ext/libcouchbase/tests/ioserver/threads-win32.cc +117 -0
- data/ext/libcouchbase/tests/ioserver/threads.h +66 -0
- data/ext/libcouchbase/tests/iotests/iotests.h +15 -0
- data/ext/libcouchbase/tests/iotests/mock-environment.cc +632 -0
- data/ext/libcouchbase/tests/iotests/mock-environment.h +480 -0
- data/ext/libcouchbase/tests/iotests/mock-unit-test.cc +67 -0
- data/ext/libcouchbase/tests/iotests/mock-unit-test.h +61 -0
- data/ext/libcouchbase/tests/iotests/serverparams.h +76 -0
- data/ext/libcouchbase/tests/iotests/t_arithmetic.cc +143 -0
- data/ext/libcouchbase/tests/iotests/t_behavior.cc +220 -0
- data/ext/libcouchbase/tests/iotests/t_configcache.cc +117 -0
- data/ext/libcouchbase/tests/iotests/t_confmon.cc +223 -0
- data/ext/libcouchbase/tests/iotests/t_durability.cc +1108 -0
- data/ext/libcouchbase/tests/iotests/t_eerrs.cc +121 -0
- data/ext/libcouchbase/tests/iotests/t_errmap.cc +181 -0
- data/ext/libcouchbase/tests/iotests/t_forward.cc +118 -0
- data/ext/libcouchbase/tests/iotests/t_get.cc +512 -0
- data/ext/libcouchbase/tests/iotests/t_http.cc +438 -0
- data/ext/libcouchbase/tests/iotests/t_iops.cc +175 -0
- data/ext/libcouchbase/tests/iotests/t_lock.cc +274 -0
- data/ext/libcouchbase/tests/iotests/t_misc.cc +777 -0
- data/ext/libcouchbase/tests/iotests/t_mutate.cc +609 -0
- data/ext/libcouchbase/tests/iotests/t_n1ql.cc +270 -0
- data/ext/libcouchbase/tests/iotests/t_netfail.cc +778 -0
- data/ext/libcouchbase/tests/iotests/t_obseqno.cc +156 -0
- data/ext/libcouchbase/tests/iotests/t_regression.cc +321 -0
- data/ext/libcouchbase/tests/iotests/t_sched.cc +87 -0
- data/ext/libcouchbase/tests/iotests/t_serverops.cc +231 -0
- data/ext/libcouchbase/tests/iotests/t_smoke.cc +528 -0
- data/ext/libcouchbase/tests/iotests/t_snappy.cc +316 -0
- data/ext/libcouchbase/tests/iotests/t_subdoc.cc +857 -0
- data/ext/libcouchbase/tests/iotests/t_syncmode.cc +64 -0
- data/ext/libcouchbase/tests/iotests/t_views.cc +417 -0
- data/ext/libcouchbase/tests/iotests/testutil.cc +251 -0
- data/ext/libcouchbase/tests/iotests/testutil.h +163 -0
- data/ext/libcouchbase/tests/mc/mctest.h +119 -0
- data/ext/libcouchbase/tests/mc/pktmaker.h +101 -0
- data/ext/libcouchbase/tests/mc/t_alloc.cc +269 -0
- data/ext/libcouchbase/tests/mc/t_context.cc +100 -0
- data/ext/libcouchbase/tests/mc/t_flush.cc +185 -0
- data/ext/libcouchbase/tests/mc/t_forward.cc +239 -0
- data/ext/libcouchbase/tests/mc/t_ioflush.cc +102 -0
- data/ext/libcouchbase/tests/mc/t_iovcursor.cc +173 -0
- data/ext/libcouchbase/tests/mocksupport/procutil.c +305 -0
- data/ext/libcouchbase/tests/mocksupport/procutil.h +89 -0
- data/ext/libcouchbase/tests/mocksupport/server.c +391 -0
- data/ext/libcouchbase/tests/mocksupport/server.h +72 -0
- data/ext/libcouchbase/tests/mocksupport/timeout.c +69 -0
- data/ext/libcouchbase/tests/nonio_tests.cc +23 -0
- data/ext/libcouchbase/tests/rdb/rdbtest.h +133 -0
- data/ext/libcouchbase/tests/rdb/t_basic.cc +128 -0
- data/ext/libcouchbase/tests/rdb/t_bigalloc.cc +93 -0
- data/ext/libcouchbase/tests/rdb/t_refs.cc +112 -0
- data/ext/libcouchbase/tests/socktests/socktest.cc +344 -0
- data/ext/libcouchbase/tests/socktests/socktest.h +447 -0
- data/ext/libcouchbase/tests/socktests/t_basic.cc +143 -0
- data/ext/libcouchbase/tests/socktests/t_ctx.cc +73 -0
- data/ext/libcouchbase/tests/socktests/t_manager.cc +159 -0
- data/ext/libcouchbase/tests/socktests/t_putex.cc +256 -0
- data/ext/libcouchbase/tests/socktests/t_read.cc +187 -0
- data/ext/libcouchbase/tests/socktests/t_reentrant.cc +143 -0
- data/ext/libcouchbase/tests/socktests/t_ssl.cc +80 -0
- data/ext/libcouchbase/tests/socktests/t_write.cc +95 -0
- data/ext/libcouchbase/tests/start_mock.bat +15 -0
- data/ext/libcouchbase/tests/start_mock.sh +42 -0
- data/ext/libcouchbase/tests/unit_tests.cc +43 -0
- data/ext/libcouchbase/tests/vbucket/confdata/bad.json +101 -0
- data/ext/libcouchbase/tests/vbucket/confdata/full_25.json +363 -0
- data/ext/libcouchbase/tests/vbucket/confdata/ketama_expected.json +2562 -0
- data/ext/libcouchbase/tests/vbucket/confdata/map_node_present_nodesext_missing_nodes.json +94 -0
- data/ext/libcouchbase/tests/vbucket/confdata/memd_25.json +90 -0
- data/ext/libcouchbase/tests/vbucket/confdata/memd_30.json +1 -0
- data/ext/libcouchbase/tests/vbucket/confdata/memd_45.json +1 -0
- data/ext/libcouchbase/tests/vbucket/confdata/memd_ketama_config.json +31 -0
- data/ext/libcouchbase/tests/vbucket/confdata/terse_25.json +291 -0
- data/ext/libcouchbase/tests/vbucket/confdata/terse_30.json +1 -0
- data/ext/libcouchbase/tests/vbucket/t_config.cc +386 -0
- data/ext/libcouchbase/tools/CMakeLists.txt +80 -0
- data/ext/libcouchbase/tools/cbc-handlers.h +636 -0
- data/ext/libcouchbase/tools/cbc-n1qlback.cc +496 -0
- data/ext/libcouchbase/tools/cbc-pillowfight.cc +1230 -0
- data/ext/libcouchbase/tools/cbc-proxy.cc +534 -0
- data/ext/libcouchbase/tools/cbc-subdoc.cc +825 -0
- data/ext/libcouchbase/tools/cbc.cc +1928 -0
- data/ext/libcouchbase/tools/common/histogram.cc +44 -0
- data/ext/libcouchbase/tools/common/histogram.h +23 -0
- data/ext/libcouchbase/tools/common/options.cc +451 -0
- data/ext/libcouchbase/tools/common/options.h +90 -0
- data/ext/libcouchbase/tools/docgen/docgen.h +495 -0
- data/ext/libcouchbase/tools/docgen/loc.h +211 -0
- data/ext/libcouchbase/tools/docgen/placeholders.h +211 -0
- data/ext/libcouchbase/tools/docgen/seqgen.h +122 -0
- data/ext/libcouchbase/tools/extract-packets.rb +110 -0
- data/ext/libcouchbase/tools/linenoise/linenoise.c +1199 -0
- data/ext/libcouchbase/tools/linenoise/linenoise.h +73 -0
- data/lib/mt-libcouchbase/bucket.rb +825 -0
- data/lib/mt-libcouchbase/callbacks.rb +69 -0
- data/lib/mt-libcouchbase/connection.rb +896 -0
- data/lib/mt-libcouchbase/design_docs.rb +92 -0
- data/lib/mt-libcouchbase/error.rb +68 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdbase.rb +23 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdcounter.rb +36 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdendure.rb +26 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdfts.rb +24 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdget.rb +30 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdgetreplica.rb +49 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdhttp.rb +58 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdn1ql.rb +40 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdobseqno.rb +33 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdobserve.rb +30 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdstore.rb +40 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdstoredur.rb +45 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdsubdoc.rb +61 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdverbosity.rb +29 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/cmdviewquery.rb +61 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/contigbuf.rb +14 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/create_st.rb +15 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/create_st0.rb +23 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/create_st1.rb +26 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/create_st2.rb +32 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/create_st3.rb +26 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/crst_u.rb +20 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/durability_opts_st_v.rb +11 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/durability_opts_t.rb +14 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/durabilityopt_sv0.rb +63 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/enums.rb +1007 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/fragbuf.rb +18 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/ftshandle.rb +7 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/histogram.rb +34 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/http_request_t.rb +7 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/keybuf.rb +20 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/multicmd_ctx.rb +30 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/mutation_token.rb +17 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/n1qlhandle.rb +7 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/n1qlparams.rb +7 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respbase.rb +29 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respcounter.rb +32 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respendure.rb +49 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respfts.rb +40 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respget.rb +44 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/resphttp.rb +48 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respmcversion.rb +38 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respn1ql.rb +41 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respobseqno.rb +52 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respobserve.rb +41 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respserverbase.rb +32 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respstats.rb +38 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respstore.rb +32 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respstoredur.rb +38 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respsubdoc.rb +35 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/respviewquery.rb +67 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/sdentry.rb +22 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/sdspec.rb +31 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/t.rb +7 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/valbuf.rb +22 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/valbuf_u_buf.rb +14 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase/viewhandle.rb +7 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase.rb +1175 -0
- data/lib/mt-libcouchbase/ext/mt-libcouchbase_libuv.rb +22 -0
- data/lib/mt-libcouchbase/ext/tasks.rb +39 -0
- data/lib/mt-libcouchbase/n1ql.rb +80 -0
- data/lib/mt-libcouchbase/query_full_text.rb +147 -0
- data/lib/mt-libcouchbase/query_n1ql.rb +123 -0
- data/lib/mt-libcouchbase/query_view.rb +135 -0
- data/lib/mt-libcouchbase/results_fiber.rb +281 -0
- data/lib/mt-libcouchbase/results_native.rb +220 -0
- data/lib/mt-libcouchbase/subdoc_request.rb +139 -0
- data/lib/mt-libcouchbase/version.rb +5 -0
- data/lib/mt-libcouchbase.rb +40 -0
- data/mt-libcouchbase.gemspec +68 -0
- data/spec/bucket_spec.rb +290 -0
- data/spec/connection_spec.rb +257 -0
- data/spec/design_docs_spec.rb +31 -0
- data/spec/error_spec.rb +26 -0
- data/spec/fts_spec.rb +135 -0
- data/spec/n1ql_spec.rb +260 -0
- data/spec/results_libuv_spec.rb +244 -0
- data/spec/results_native_spec.rb +259 -0
- data/spec/seed/2016-10-25T043505Z/2016-10-25T043505Z-full/bucket-default/design.json +1 -0
- data/spec/seed/2016-10-25T043505Z/2016-10-25T043505Z-full/bucket-default/node-127.0.0.1%3A8091/data-0000.cbb +0 -0
- data/spec/seed/2016-10-25T043505Z/2016-10-25T043505Z-full/bucket-default/node-127.0.0.1%3A8091/failover.json +1 -0
- data/spec/seed/2016-10-25T043505Z/2016-10-25T043505Z-full/bucket-default/node-127.0.0.1%3A8091/meta.json +1 -0
- data/spec/seed/2016-10-25T043505Z/2016-10-25T043505Z-full/bucket-default/node-127.0.0.1%3A8091/seqno.json +1 -0
- data/spec/seed/2016-10-25T043505Z/2016-10-25T043505Z-full/bucket-default/node-127.0.0.1%3A8091/snapshot_markers.json +1 -0
- data/spec/subdoc_spec.rb +192 -0
- data/spec/view_spec.rb +201 -0
- data/windows_build.md +36 -0
- metadata +873 -0
@@ -0,0 +1,4089 @@
|
|
1
|
+
/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
|
2
|
+
/*
|
3
|
+
* Copyright 2010-2017 Couchbase, Inc.
|
4
|
+
*
|
5
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
6
|
+
* you may not use this file except in compliance with the License.
|
7
|
+
* You may obtain a copy of the License at
|
8
|
+
*
|
9
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
10
|
+
*
|
11
|
+
* Unless required by applicable law or agreed to in writing, software
|
12
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
13
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
14
|
+
* See the License for the specific language governing permissions and
|
15
|
+
* limitations under the License.
|
16
|
+
*/
|
17
|
+
|
18
|
+
#ifndef LIBCOUCHBASE_COUCHBASE_H
|
19
|
+
#define LIBCOUCHBASE_COUCHBASE_H 1
|
20
|
+
|
21
|
+
/**
|
22
|
+
* @file
|
23
|
+
* Main header file for Couchbase
|
24
|
+
*/
|
25
|
+
|
26
|
+
#define LCB_CONFIG_MCD_PORT 11210
|
27
|
+
#define LCB_CONFIG_MCD_SSL_PORT 11207
|
28
|
+
#define LCB_CONFIG_HTTP_PORT 8091
|
29
|
+
#define LCB_CONFIG_HTTP_SSL_PORT 18091
|
30
|
+
#define LCB_CONFIG_MCCOMPAT_PORT 11211
|
31
|
+
|
32
|
+
struct lcb_st;
|
33
|
+
|
34
|
+
/**
|
35
|
+
* @ingroup lcb-init
|
36
|
+
* Library handle representing a connection to a cluster and its data buckets. The contents
|
37
|
+
* of this structure are opaque.
|
38
|
+
* @see lcb_create
|
39
|
+
* @see lcb_destroy
|
40
|
+
*/
|
41
|
+
typedef struct lcb_st *lcb_t;
|
42
|
+
struct lcb_http_request_st;
|
43
|
+
typedef struct lcb_http_request_st *lcb_http_request_t;
|
44
|
+
|
45
|
+
#include <stddef.h>
|
46
|
+
#include <time.h>
|
47
|
+
#include <stdarg.h>
|
48
|
+
#include <stdio.h>
|
49
|
+
#include <libcouchbase/sysdefs.h>
|
50
|
+
#include <libcouchbase/assert.h>
|
51
|
+
#include <libcouchbase/visibility.h>
|
52
|
+
#include <libcouchbase/error.h>
|
53
|
+
#include <libcouchbase/iops.h>
|
54
|
+
#include <libcouchbase/http.h>
|
55
|
+
#include <libcouchbase/configuration.h>
|
56
|
+
#include <libcouchbase/kvbuf.h>
|
57
|
+
#include <libcouchbase/auth.h>
|
58
|
+
#include <libcouchbase/tracing.h>
|
59
|
+
#include <libcouchbase/_cxxwrap.h>
|
60
|
+
#include <libcouchbase/cntl.h>
|
61
|
+
|
62
|
+
#ifdef __cplusplus
|
63
|
+
extern "C"{
|
64
|
+
#endif
|
65
|
+
|
66
|
+
typedef lcb_U8 lcb_datatype_t;
|
67
|
+
typedef lcb_U32 lcb_USECS;
|
68
|
+
|
69
|
+
|
70
|
+
/******************************************************************************
|
71
|
+
******************************************************************************
|
72
|
+
******************************************************************************
|
73
|
+
** INITIALIZATION **
|
74
|
+
******************************************************************************
|
75
|
+
******************************************************************************
|
76
|
+
******************************************************************************/
|
77
|
+
|
78
|
+
/**
|
79
|
+
* @ingroup lcb-public-api
|
80
|
+
* @defgroup lcb-init Initialization
|
81
|
+
*
|
82
|
+
* @details
|
83
|
+
*
|
84
|
+
* To communicate with a Couchbase cluster, a new library handle instance is
|
85
|
+
* created in the form of an lcb_t. To create such an object, the lcb_create()
|
86
|
+
* function is called, passing it a structure of type lcb_create_st. The structure
|
87
|
+
* acts as a container for a union of other structures which are extended
|
88
|
+
* as more features are added. This container is forwards and backwards
|
89
|
+
* compatible, meaning that if the structure is extended, you code and application
|
90
|
+
* will still function if using an older version of the structure. The current
|
91
|
+
* sub-field of the lcb_create_st structure is the `v3` field.
|
92
|
+
*
|
93
|
+
* Connecting to the cluster involes the client knowing the necessary
|
94
|
+
* information needed to actually locate its services and connect to it.
|
95
|
+
*
|
96
|
+
* A connection specification consists of:
|
97
|
+
*
|
98
|
+
* 1. One or more hosts which comprise the cluster
|
99
|
+
* 2. The name of the bucket to access and perform operations on
|
100
|
+
* 3. The credentials of the bucket
|
101
|
+
*
|
102
|
+
* All these options are specified within the form of a URI in the form of
|
103
|
+
*
|
104
|
+
* `couchbase://$HOSTS/$BUCKET?$OPTIONS`
|
105
|
+
*
|
106
|
+
* @note
|
107
|
+
* If any of the fields (hosts, bucket, options) contain the `/` character then
|
108
|
+
* it _must_ be url-encoded; thus a bucket named `foo/bar` would be specified
|
109
|
+
* as `couchbase:///foo%2Fbar`
|
110
|
+
*
|
111
|
+
* @par Hosts
|
112
|
+
*
|
113
|
+
* In the most typical use case, you would specify a list of several hostnames
|
114
|
+
* delimited by a comma (`,`); each host specified should be a member of the
|
115
|
+
* cluster. The library will use this list to initially connect to the cluster.
|
116
|
+
*
|
117
|
+
* Note that it is not necessary to specify _all_ the nodes of the cluster as in
|
118
|
+
* a normal situation the library will only initially connect to one of the nodes.
|
119
|
+
* Passing multiple nodes increases the chance of a connection succeeding even
|
120
|
+
* if some of the nodes are currently down. Once connected to the cluster, the
|
121
|
+
* client will update itself with the other nodes actually found within the
|
122
|
+
* cluster and discard the list passed to it
|
123
|
+
*
|
124
|
+
* You can specify multiple hosts like so:
|
125
|
+
*
|
126
|
+
* `couchbase://foo.com,bar.com,baz.com`
|
127
|
+
*
|
128
|
+
* Or a single host:
|
129
|
+
*
|
130
|
+
* `couchbase://localhost`
|
131
|
+
*
|
132
|
+
* #### Specifying Ports and Protocol Options
|
133
|
+
*
|
134
|
+
* The default `couchbase://` scheme will assume all hosts and/or ports
|
135
|
+
* specify the _memcached_ port. If no port is specified, it is assumed
|
136
|
+
* that the port is _11210). For more extended options there are additional
|
137
|
+
* schemes available:
|
138
|
+
*
|
139
|
+
* * `couchbases://` - Will assume all ports refer to the SSL-enabled memcached
|
140
|
+
* ports. This setting implicitly enables SSL on the instance as well. If no
|
141
|
+
* ports are provided for the hosts, the implicit port for each host will be
|
142
|
+
* _11207_.
|
143
|
+
*
|
144
|
+
* * `http://` - Will assume all ports refer to the HTTP REST API ports used
|
145
|
+
* by Couchbase 2.2 and lower. These are also used when connecting to a
|
146
|
+
* memcached bucket. If no port is specified it will be assumed the port is
|
147
|
+
* _8091_.
|
148
|
+
*
|
149
|
+
* ### Bucket
|
150
|
+
*
|
151
|
+
* A bucket may be specified by using the optional _path_ component of the URI
|
152
|
+
* For protected buckets a password will still need to be supplied out of band.
|
153
|
+
*
|
154
|
+
* * `couchbase://1.1.1.1,2.2.2.2,3.3.3.3/users` - Connect to the `users`
|
155
|
+
* bucket.
|
156
|
+
*
|
157
|
+
* ### Options
|
158
|
+
*
|
159
|
+
* @warning The key-value options here are considered to be an uncommitted interface
|
160
|
+
* as their names may change.
|
161
|
+
*
|
162
|
+
* Options can be specified as the _query_ part of the connection string,
|
163
|
+
* for example:
|
164
|
+
*
|
165
|
+
* `couchbase://cbnode.net/beer?operation_timeout=10000000`.
|
166
|
+
*
|
167
|
+
* Options may either be appropriate _key_ parameters for lcb_cntl_string()
|
168
|
+
* or one of the following:
|
169
|
+
*
|
170
|
+
* * `boostrap_on` - specify bootstrap protocols. Values can be `http` to force
|
171
|
+
* old-style bootstrap mode for legacy clusters, `cccp` to force bootstrap
|
172
|
+
* over the memcached port (For clusters 2.5 and above), or `all` to try with
|
173
|
+
* _cccp_ and revert to _http_
|
174
|
+
*
|
175
|
+
* * `truststorepath` - Specify the path (on the local filesystem) to the server's
|
176
|
+
* SSL certificate truststore. Only applicable if SSL is being used (i.e. the
|
177
|
+
* scheme is `couchbases`). The trust store is optional, and when missing,
|
178
|
+
* the library will use `certpath` as location for verification, and expect
|
179
|
+
* any extra certificates to be concatenated in there.
|
180
|
+
*
|
181
|
+
* * `certpath` - Specify the path (on the local filesystem) to the server's
|
182
|
+
* SSL certificate. Only applicable if SSL is being used (i.e. the scheme is
|
183
|
+
* `couchbases`)
|
184
|
+
*
|
185
|
+
* * `keypath` - Specify the path (on the local filesystem) to the client
|
186
|
+
* SSL private key. Only applicable if SSL client certificate authentication
|
187
|
+
* is being used (i.e. the scheme is `couchbases` and `certpath` contains
|
188
|
+
* client certificate). Read more in the server documentation:
|
189
|
+
* https://developer.couchbase.com/documentation/server/5.0/security/security-certs-auth.html
|
190
|
+
*
|
191
|
+
* ### Bucket Identification and Credentials
|
192
|
+
*
|
193
|
+
* The most common settings you will wish to modify are the bucket name
|
194
|
+
* and the credentials field (`user` and `passwd`). If a
|
195
|
+
* `bucket` is not specified it will revert to the `default` bucket (i.e. the
|
196
|
+
* bucket which is created when Couchbase Server is installed).
|
197
|
+
*
|
198
|
+
* The `user` and `passwd` fields authenticate for the bucket. This is only
|
199
|
+
* needed if you have configured your bucket to employ SASL auth. You can tell
|
200
|
+
* if the bucket has been configured with SASL auth by
|
201
|
+
*
|
202
|
+
* 1. Logging into the Couchbase Administration Console
|
203
|
+
* 2. Going to the _Data Buckets_ tab
|
204
|
+
* 3. Locate the row for your bucket
|
205
|
+
* 4. Expand the row into the detailed view (by clicking on the arrow at the
|
206
|
+
* left of the row)
|
207
|
+
* 5. Click on _Edit_
|
208
|
+
* 6. Inspect the _Access Control_ section in the pop-up
|
209
|
+
*
|
210
|
+
* The bucket name is specified as the _path_ portion of the URI.
|
211
|
+
*
|
212
|
+
* For security purposes, the _user_ and _passwd_ cannot be specified within
|
213
|
+
* the URI
|
214
|
+
*
|
215
|
+
*
|
216
|
+
* @note
|
217
|
+
* You may not change the bucket or credentials after initializing the handle.
|
218
|
+
*
|
219
|
+
* #### Bootstrap Options
|
220
|
+
*
|
221
|
+
* The default configuration process will attempt to bootstrap first from
|
222
|
+
* the new memcached configuration protocol (CCCP) and if that fails, use
|
223
|
+
* the "HTTP" protocol via the REST API.
|
224
|
+
*
|
225
|
+
* The CCCP configuration will by default attempt to connect to one of
|
226
|
+
* the nodes specified on the port 11201. While normally the memcached port
|
227
|
+
* is determined by the configuration itself, this is not possible when
|
228
|
+
* the configuration has not been attained. You may specify a list of
|
229
|
+
* alternate memcached servers by using the 'mchosts' field.
|
230
|
+
*
|
231
|
+
* If you wish to modify the default bootstrap protocol selection, you
|
232
|
+
* can use the `bootstrap_on` option to specify the desired bootstrap
|
233
|
+
* specification
|
234
|
+
* to use for configuration (note that the ordering of this array is
|
235
|
+
* ignored). Using this mechanism, you can disable CCCP or HTTP.
|
236
|
+
*
|
237
|
+
* To force only "new-style" bootstrap, you may use `bootstrap_on=cccp`.
|
238
|
+
* To force only "old-style" bootstrap, use `bootstrap_on=http`. To force the
|
239
|
+
* default behavior, use `bootstrap_on=all`
|
240
|
+
*
|
241
|
+
*
|
242
|
+
* @addtogroup lcb-init
|
243
|
+
* @{
|
244
|
+
*/
|
245
|
+
|
246
|
+
/** @brief Handle types @see lcb_create_st3::type */
|
247
|
+
typedef enum {
|
248
|
+
LCB_TYPE_BUCKET = 0x00, /**< Handle for data access (default) */
|
249
|
+
LCB_TYPE_CLUSTER = 0x01 /**< Handle for administrative access */
|
250
|
+
} lcb_type_t;
|
251
|
+
|
252
|
+
/**
|
253
|
+
* @brief Type of the bucket
|
254
|
+
*
|
255
|
+
* @see https://developer.couchbase.com/documentation/server/current/architecture/core-data-access-buckets.html
|
256
|
+
*/
|
257
|
+
typedef enum {
|
258
|
+
LCB_BTYPE_UNSPEC = 0x00, /**< Unknown or unspecified */
|
259
|
+
LCB_BTYPE_COUCHBASE = 0x01, /**< Data persisted and replicated */
|
260
|
+
LCB_BTYPE_EPHEMERAL = 0x02, /**< Data not persisted, but replicated */
|
261
|
+
LCB_BTYPE_MEMCACHED = 0x03 /**< Data not persisted and not replicated */
|
262
|
+
} lcb_BTYPE;
|
263
|
+
|
264
|
+
|
265
|
+
#ifndef __LCB_DOXYGEN__
|
266
|
+
/* These are definitions for some of the older fields of the `lcb_create_st`
|
267
|
+
* structure. They are here for backwards compatibility and should not be
|
268
|
+
* used by new code */
|
269
|
+
typedef enum { LCB_CONFIG_TRANSPORT_LIST_END = 0, LCB_CONFIG_TRANSPORT_HTTP = 1, LCB_CONFIG_TRANSPORT_CCCP, LCB_CONFIG_TRANSPORT_MAX } lcb_config_transport_t;
|
270
|
+
#define LCB_CREATE_V0_FIELDS const char *host; const char *user; const char *passwd; const char *bucket; struct lcb_io_opt_st *io;
|
271
|
+
#define LCB_CREATE_V1_FIELDS LCB_CREATE_V0_FIELDS lcb_type_t type;
|
272
|
+
#define LCB_CREATE_V2_FIELDS LCB_CREATE_V1_FIELDS const char *mchosts; const lcb_config_transport_t* transports;
|
273
|
+
struct lcb_create_st0 { LCB_CREATE_V0_FIELDS };
|
274
|
+
struct lcb_create_st1 { LCB_CREATE_V1_FIELDS };
|
275
|
+
struct lcb_create_st2 { LCB_CREATE_V2_FIELDS };
|
276
|
+
#endif
|
277
|
+
|
278
|
+
/**
|
279
|
+
* @brief Inner structure V3 for lcb_create().
|
280
|
+
*/
|
281
|
+
struct lcb_create_st3 {
|
282
|
+
const char *connstr; /**< Connection string */
|
283
|
+
|
284
|
+
/**
|
285
|
+
* Username to use for authentication. This should only be set when
|
286
|
+
* connecting to a server 5.0 or greater.
|
287
|
+
*/
|
288
|
+
const char *username;
|
289
|
+
|
290
|
+
/**
|
291
|
+
* Password for bucket. Can also be password for username on servers >= 5.0
|
292
|
+
*/
|
293
|
+
const char *passwd;
|
294
|
+
|
295
|
+
void *_pad_bucket; /**< @private */
|
296
|
+
struct lcb_io_opt_st *io; /**< IO Options */
|
297
|
+
lcb_type_t type;
|
298
|
+
};
|
299
|
+
|
300
|
+
/**
|
301
|
+
* @brief Inner structure V4 for lcb_create().
|
302
|
+
*
|
303
|
+
* Same as V3, but allows to supply logger (@see LCB_CNTL_LOGGER).
|
304
|
+
*/
|
305
|
+
struct lcb_create_st4 {
|
306
|
+
const char *connstr; /**< Connection string */
|
307
|
+
|
308
|
+
/**
|
309
|
+
* Username to use for authentication. This should only be set when
|
310
|
+
* connecting to a server 5.0 or greater.
|
311
|
+
*/
|
312
|
+
const char *username;
|
313
|
+
|
314
|
+
/**
|
315
|
+
* Password for bucket. Can also be password for username on servers >= 5.0
|
316
|
+
*/
|
317
|
+
const char *passwd;
|
318
|
+
|
319
|
+
lcb_logprocs *logger; /**< Logger */
|
320
|
+
struct lcb_io_opt_st *io; /**< IO Options */
|
321
|
+
lcb_type_t type;
|
322
|
+
};
|
323
|
+
|
324
|
+
/**
|
325
|
+
* @brief Wrapper structure for lcb_create()
|
326
|
+
* @see lcb_create_st3
|
327
|
+
*/
|
328
|
+
struct lcb_create_st {
|
329
|
+
/** Indicates which field in the @ref lcb_CRST_u union should be used. Set this to `3` */
|
330
|
+
int version;
|
331
|
+
|
332
|
+
/**This union contains the set of current and historical options. The
|
333
|
+
* The #v3 field should be used. */
|
334
|
+
union lcb_CRST_u {
|
335
|
+
struct lcb_create_st0 v0;
|
336
|
+
struct lcb_create_st1 v1;
|
337
|
+
struct lcb_create_st2 v2;
|
338
|
+
struct lcb_create_st3 v3; /**< Use this field */
|
339
|
+
struct lcb_create_st4 v4;
|
340
|
+
} v;
|
341
|
+
LCB_DEPR_CTORS_CRST
|
342
|
+
};
|
343
|
+
|
344
|
+
/**
|
345
|
+
* @brief Create an instance of lcb.
|
346
|
+
* @param instance Where the instance should be returned
|
347
|
+
* @param options How to create the libcouchbase instance
|
348
|
+
* @return LCB_SUCCESS on success
|
349
|
+
*
|
350
|
+
*
|
351
|
+
* ### Examples
|
352
|
+
* Create an instance using the default values:
|
353
|
+
*
|
354
|
+
* @code{.c}
|
355
|
+
* lcb_t instance;
|
356
|
+
* lcb_error_t err = lcb_create(&instance, NULL);
|
357
|
+
* if (err != LCB_SUCCESS) {
|
358
|
+
* fprintf(stderr, "Failed to create instance: %s\n", lcb_strerror(NULL, err));
|
359
|
+
* exit(EXIT_FAILURE);
|
360
|
+
* }
|
361
|
+
* @endcode
|
362
|
+
*
|
363
|
+
* Specify server list
|
364
|
+
*
|
365
|
+
* @code{.c}
|
366
|
+
* struct lcb_create_st options;
|
367
|
+
* memset(&options, 0, sizeof(options));
|
368
|
+
* options.version = 3;
|
369
|
+
* options.v.v3.connstr = "couchbase://host1,host2,host3";
|
370
|
+
* err = lcb_create(&instance, &options);
|
371
|
+
* @endcode
|
372
|
+
*
|
373
|
+
*
|
374
|
+
* Create a handle for data requests to protected bucket
|
375
|
+
*
|
376
|
+
* @code{.c}
|
377
|
+
* struct lcb_create_st options;
|
378
|
+
* memset(&options, 0, sizeof(options));
|
379
|
+
* options.version = 3;
|
380
|
+
* options.v.v3.host = "couchbase://example.com,example.org/protected"
|
381
|
+
* options.v.v3.passwd = "secret";
|
382
|
+
* err = lcb_create(&instance, &options);
|
383
|
+
* @endcode
|
384
|
+
* @committed
|
385
|
+
* @see lcb_create_st3
|
386
|
+
*/
|
387
|
+
LIBCOUCHBASE_API
|
388
|
+
lcb_error_t lcb_create(lcb_t *instance, const struct lcb_create_st *options);
|
389
|
+
|
390
|
+
/**
|
391
|
+
* @brief Schedule the initial connection
|
392
|
+
* This function will schedule the initial connection for the handle. This
|
393
|
+
* function _must_ be called before any operations can be performed.
|
394
|
+
*
|
395
|
+
* lcb_set_bootstrap_callback() or lcb_get_bootstrap_status() can be used to
|
396
|
+
* determine if the scheduled connection completed successfully.
|
397
|
+
*
|
398
|
+
* @par Synchronous Usage
|
399
|
+
* @code{.c}
|
400
|
+
* lcb_error_t rc = lcb_connect(instance);
|
401
|
+
* if (rc != LCB_SUCCESS) {
|
402
|
+
* your_error_handling(rc);
|
403
|
+
* }
|
404
|
+
* lcb_wait(instance);
|
405
|
+
* rc = lcb_get_bootstrap_status(instance);
|
406
|
+
* if (rc != LCB_SUCCESS) {
|
407
|
+
* your_error_handler(rc);
|
408
|
+
* }
|
409
|
+
* @endcode
|
410
|
+
* @committed
|
411
|
+
*/
|
412
|
+
LIBCOUCHBASE_API
|
413
|
+
lcb_error_t lcb_connect(lcb_t instance);
|
414
|
+
|
415
|
+
/**
|
416
|
+
* Bootstrap callback. Invoked once the instance is ready to perform operations
|
417
|
+
* @param instance The instance which was bootstrapped
|
418
|
+
* @param err The error code received. If this is not LCB_SUCCESS then the
|
419
|
+
* instance is not bootstrapped and must be recreated
|
420
|
+
*
|
421
|
+
* @attention This callback only receives information during instantiation.
|
422
|
+
* @committed
|
423
|
+
*/
|
424
|
+
typedef void (*lcb_bootstrap_callback)(lcb_t instance, lcb_error_t err);
|
425
|
+
|
426
|
+
/**
|
427
|
+
* @brief Set the callback for notification of success or failure of
|
428
|
+
* initial connection.
|
429
|
+
*
|
430
|
+
* @param instance the instance
|
431
|
+
* @param callback the callback to set. If `NULL`, return the existing callback
|
432
|
+
* @return The existing (and previous) callback.
|
433
|
+
* @see lcb_connect()
|
434
|
+
* @see lcb_get_bootstrap_status()
|
435
|
+
*/
|
436
|
+
LIBCOUCHBASE_API
|
437
|
+
lcb_bootstrap_callback
|
438
|
+
lcb_set_bootstrap_callback(lcb_t instance, lcb_bootstrap_callback callback);
|
439
|
+
|
440
|
+
/**
|
441
|
+
* @brief Gets the initial bootstrap status
|
442
|
+
*
|
443
|
+
* This is an alternative to using the lcb_bootstrap_callback() and may be used
|
444
|
+
* after the initial lcb_connect() and lcb_wait() sequence.
|
445
|
+
* @param instance
|
446
|
+
* @return LCB_SUCCESS if properly bootstrapped or an error code otherwise.
|
447
|
+
*
|
448
|
+
* @attention
|
449
|
+
* Calling this function only makes sense during instantiation.
|
450
|
+
* @committed
|
451
|
+
*/
|
452
|
+
LIBCOUCHBASE_API
|
453
|
+
lcb_error_t
|
454
|
+
lcb_get_bootstrap_status(lcb_t instance);
|
455
|
+
|
456
|
+
/**
|
457
|
+
* Sets the authenticator object for the instance. This may be done anytime, but
|
458
|
+
* should probably be done before calling `lcb_connect()` for best effect.
|
459
|
+
*
|
460
|
+
* @param instance the handle
|
461
|
+
* @param auth the authenticator object used. The library will increase the
|
462
|
+
* refcount on the authenticator object.
|
463
|
+
*/
|
464
|
+
LIBCOUCHBASE_API
|
465
|
+
void
|
466
|
+
lcb_set_auth(lcb_t instance, lcb_AUTHENTICATOR *auth);
|
467
|
+
/**@}*/
|
468
|
+
|
469
|
+
|
470
|
+
|
471
|
+
/**
|
472
|
+
* @ingroup lcb-public-api
|
473
|
+
* @defgroup lcb-kv-api Key/Value
|
474
|
+
*
|
475
|
+
* @brief Preview APIs for performing commands
|
476
|
+
*
|
477
|
+
* @details
|
478
|
+
* Basic command and structure definitions for public API. This represents the
|
479
|
+
* "V3" API of libcouchbase. This API replaces the legacy API (which now wraps
|
480
|
+
* this one). It contains common definitions for scheduling, response structures
|
481
|
+
* and callback signatures.
|
482
|
+
*
|
483
|
+
* @addtogroup lcb-kv-api
|
484
|
+
* @{
|
485
|
+
*/
|
486
|
+
|
487
|
+
/**
|
488
|
+
* @name Creating Commands
|
489
|
+
* @details
|
490
|
+
*
|
491
|
+
* Issuing a command to the Cluster involves selecting the correct command
|
492
|
+
* structure, populating it with the data relevant for the command, optionally
|
493
|
+
* associating the command with your own application data, issuing the command
|
494
|
+
* to a spooling function, and finally receiving the response.
|
495
|
+
*
|
496
|
+
* Command structures all derive from the common @ref lcb_CMDBASE structure. This
|
497
|
+
* structure defines the common fields for all commands.
|
498
|
+
*
|
499
|
+
* Almost all commands need to contain a key, which should be assigned using
|
500
|
+
* the LCB_CMD_SET_KEY() macro.
|
501
|
+
*
|
502
|
+
* @{*/
|
503
|
+
|
504
|
+
#define LCB_CMD_BASE \
|
505
|
+
/**Common flags for the command. These modify the command itself. Currently
|
506
|
+
the lower 16 bits of this field are reserved, and the higher 16 bits are
|
507
|
+
used for individual commands.*/ \
|
508
|
+
lcb_U32 cmdflags; \
|
509
|
+
\
|
510
|
+
/**Specify the expiration time. This is either an absolute Unix time stamp
|
511
|
+
or a relative offset from now, in seconds. If the value of this number
|
512
|
+
is greater than the value of thirty days in seconds, then it is a Unix
|
513
|
+
timestamp.
|
514
|
+
|
515
|
+
This field is used in mutation operations (lcb_store3()) to indicate
|
516
|
+
the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock
|
517
|
+
option to indicate the lock expiration itself. */ \
|
518
|
+
lcb_U32 exptime; \
|
519
|
+
\
|
520
|
+
/**The known CAS of the item. This is passed to mutation to commands to
|
521
|
+
ensure the item is only changed if the server-side CAS value matches the
|
522
|
+
one specified here. For other operations (such as lcb_CMDENDURE) this
|
523
|
+
is used to ensure that the item has been persisted/replicated to a number
|
524
|
+
of servers with the value specified here. */ \
|
525
|
+
lcb_U64 cas; \
|
526
|
+
\
|
527
|
+
/**The key for the document itself. This should be set via LCB_CMD_SET_KEY() */ \
|
528
|
+
lcb_KEYBUF key; \
|
529
|
+
\
|
530
|
+
/** \volatile */ \
|
531
|
+
lcb_KEYBUF _hashkey
|
532
|
+
|
533
|
+
/**@brief Common ABI header for all commands. _Any_ command may be safely
|
534
|
+
* casted to this type.*/
|
535
|
+
typedef struct lcb_CMDBASE {
|
536
|
+
LCB_CMD_BASE;
|
537
|
+
} lcb_CMDBASE;
|
538
|
+
|
539
|
+
/**
|
540
|
+
* Flag for lcb_CMDBASE::cmdflags which indicates that the lcb_CMDBASE::cookie
|
541
|
+
* is a special callback object. This flag is used internally within the
|
542
|
+
* library.
|
543
|
+
*
|
544
|
+
* @internal
|
545
|
+
*/
|
546
|
+
#define LCB_CMD_F_INTERNAL_CALLBACK (1 << 0)
|
547
|
+
|
548
|
+
/**
|
549
|
+
* If this flag is set, then multiple authentication credentials will be passed
|
550
|
+
* to the server. By default only the bucket's credentials (i.e. bucket SASL
|
551
|
+
* password) are passed.
|
552
|
+
*/
|
553
|
+
#define LCB_CMD_F_MULTIAUTH (1<<1)
|
554
|
+
|
555
|
+
/**
|
556
|
+
* Set the key for the command.
|
557
|
+
* @param cmd A command derived from lcb_CMDBASE
|
558
|
+
* @param keybuf the buffer for the key
|
559
|
+
* @param keylen the length of the key.
|
560
|
+
*
|
561
|
+
* @code{.c}
|
562
|
+
* lcb_CMDGET cmd = { 0 };
|
563
|
+
* LCB_CMD_SET_KEY(&cmd, "key", strlen("key"));
|
564
|
+
* @endcode
|
565
|
+
*
|
566
|
+
* The storage for `keybuf` may be released or modified after the command has
|
567
|
+
* been spooled.
|
568
|
+
*/
|
569
|
+
#define LCB_CMD_SET_KEY(cmd, keybuf, keylen) \
|
570
|
+
LCB_KREQ_SIMPLE(&(cmd)->key, keybuf, keylen)
|
571
|
+
|
572
|
+
/**
|
573
|
+
* Sets the vBucket ID for the item. This accomplishes the same effect as
|
574
|
+
* _hashkey_ except that this assumes the vBucket has already been obtained.
|
575
|
+
*
|
576
|
+
* The intent of this API is to override the default vBucket hashing/calculation.
|
577
|
+
*
|
578
|
+
* @param cmd the command structure
|
579
|
+
* @param vbid the vBucket ID for the key.
|
580
|
+
* @volatile
|
581
|
+
*/
|
582
|
+
#define LCB_CMD__SETVBID(cmd, vbid) do { \
|
583
|
+
(cmd)->_hashkey.type = LCB_KV_VBID; \
|
584
|
+
(cmd)->_hashkey.contig.nbytes = vbid; \
|
585
|
+
} while (0);
|
586
|
+
/**@}*/
|
587
|
+
|
588
|
+
/**
|
589
|
+
* @name Receiving Responses
|
590
|
+
* @details
|
591
|
+
*
|
592
|
+
* This section describes the APIs used in receiving responses.
|
593
|
+
*
|
594
|
+
* Each command will have a callback invoked (typically once, for some commands
|
595
|
+
* this may be more than once) with a response structure. The response structure
|
596
|
+
* will be of a type that extends lcb_RESPBASE. The response structure should
|
597
|
+
* not be modified and any of its fields should be considered to point to memory
|
598
|
+
* which will be released after the callback exits.
|
599
|
+
*
|
600
|
+
* The common response header contains the lcb_RESPBASE::cookie field which
|
601
|
+
* is the pointer to your application context (passed as the second argument
|
602
|
+
* to the spooling function) and allows you to associate a specific command
|
603
|
+
* with a specific response.
|
604
|
+
*
|
605
|
+
* The header will also contain the key (lcb_RESPBASE::key) field which can
|
606
|
+
* also help identify the specific command. This is useful if you maintain a
|
607
|
+
* single _cookie_ for multiple commands, and have per-item specific data
|
608
|
+
* you wish to associate within the _cookie_ itself.
|
609
|
+
*
|
610
|
+
* Success or failure of the operation is signalled through the lcb_RESPBASE::rc
|
611
|
+
* field. Note that even in the case of failure, the lcb_RESPBASE::cookie and
|
612
|
+
* lcb_RESPBASE::key fields will _always_ be populated.
|
613
|
+
*
|
614
|
+
* Most commands also return the CAS of the item (as it exists on the server)
|
615
|
+
* and this is placed inside the lcb_RESPBASE::cas field, however it is
|
616
|
+
* only valid in the case where lcb_RESPBASE::rc is LCB_SUCCESS.
|
617
|
+
*
|
618
|
+
* @{
|
619
|
+
*/
|
620
|
+
|
621
|
+
#define LCB_RESP_BASE \
|
622
|
+
/**
|
623
|
+
Application-defined pointer passed as the `cookie` parameter when
|
624
|
+
scheduling the command.
|
625
|
+
*/ \
|
626
|
+
void *cookie; \
|
627
|
+
const void *key; /**< Key for request */ \
|
628
|
+
lcb_SIZE nkey; /**< Size of key */ \
|
629
|
+
lcb_CAS cas; /**< CAS for response (if applicable) */ \
|
630
|
+
lcb_error_t rc; /**< Status code */ \
|
631
|
+
lcb_U16 version; /**< ABI version for response */ \
|
632
|
+
/** Response specific flags. see ::lcb_RESPFLAGS */ \
|
633
|
+
lcb_U16 rflags;
|
634
|
+
|
635
|
+
|
636
|
+
/**
|
637
|
+
* @brief
|
638
|
+
* Base response structure for callbacks.
|
639
|
+
* All responses structures derive from this ABI.
|
640
|
+
*/
|
641
|
+
typedef struct {
|
642
|
+
LCB_RESP_BASE
|
643
|
+
} lcb_RESPBASE;
|
644
|
+
|
645
|
+
|
646
|
+
#define LCB_RESP_SERVER_FIELDS \
|
647
|
+
/** String containing the `host:port` of the server which sent this response */ \
|
648
|
+
const char *server;
|
649
|
+
|
650
|
+
/**
|
651
|
+
* @brief Base structure for informational commands from servers
|
652
|
+
* This contains an additional lcb_RESPSERVERBASE::server field containing the
|
653
|
+
* server which emitted this response.
|
654
|
+
*/
|
655
|
+
typedef struct {
|
656
|
+
LCB_RESP_BASE
|
657
|
+
LCB_RESP_SERVER_FIELDS
|
658
|
+
} lcb_RESPSERVERBASE;
|
659
|
+
|
660
|
+
/** @ingroup lcb-mutation-tokens */
|
661
|
+
typedef struct lcb_MUTATION_TOKEN {
|
662
|
+
lcb_U64 uuid_; /**< Use LCB_MUTATION_TOKEN_ID() */
|
663
|
+
lcb_U64 seqno_; /**< Use LCB_MUTATION_TOKEN_SEQ() */
|
664
|
+
lcb_U16 vbid_; /**< Use LCB_MUTATION_TOKEN_VB() */
|
665
|
+
} lcb_MUTATION_TOKEN;
|
666
|
+
|
667
|
+
/**
|
668
|
+
* @brief Response flags.
|
669
|
+
* These provide additional 'meta' information about the response
|
670
|
+
* One of more of these values can be set in @ref lcb_RESPBASE::rflags
|
671
|
+
*/
|
672
|
+
typedef enum {
|
673
|
+
/** No more responses are to be received for this request */
|
674
|
+
LCB_RESP_F_FINAL = 0x01,
|
675
|
+
|
676
|
+
/**The response was artificially generated inside the client.
|
677
|
+
* This does not contain reply data from the server for the command, but
|
678
|
+
* rather contains the basic fields to indicate success or failure and is
|
679
|
+
* otherwise empty.
|
680
|
+
*/
|
681
|
+
LCB_RESP_F_CLIENTGEN = 0x02,
|
682
|
+
|
683
|
+
/**The response was a result of a not-my-vbucket error */
|
684
|
+
LCB_RESP_F_NMVGEN = 0x04,
|
685
|
+
|
686
|
+
/**The response has additional internal data.
|
687
|
+
* Used by lcb_resp_get_mutation_token() */
|
688
|
+
LCB_RESP_F_EXTDATA = 0x08,
|
689
|
+
|
690
|
+
/**Flag, only valid for subdoc responses, indicates that the response was
|
691
|
+
* processed using the single-operation protocol. */
|
692
|
+
LCB_RESP_F_SDSINGLE = 0x10,
|
693
|
+
|
694
|
+
/**The response has extra error information as value (see SDK-RFC-28). */
|
695
|
+
LCB_RESP_F_ERRINFO = 0x20
|
696
|
+
} lcb_RESPFLAGS;
|
697
|
+
|
698
|
+
/**
|
699
|
+
* The type of response passed to the callback. This is used to install callbacks
|
700
|
+
* for the library and to distinguish between responses if a single callback
|
701
|
+
* is used for multiple response types.
|
702
|
+
*
|
703
|
+
* @note These callbacks may conflict with the older version 2 callbacks. The
|
704
|
+
* rules are as follows:
|
705
|
+
* * If a callback has been installed using lcb_install_callback3(), then
|
706
|
+
* the older version 2 callback will not be invoked for that operation. The order
|
707
|
+
* of installation does not matter.
|
708
|
+
* * If the LCB_CALLBACK_DEFAULT callback is installed, _none_ of the version 2
|
709
|
+
* callbacks are invoked.
|
710
|
+
*/
|
711
|
+
typedef enum {
|
712
|
+
LCB_CALLBACK_DEFAULT = 0, /**< Default callback invoked as a fallback */
|
713
|
+
LCB_CALLBACK_GET, /**< lcb_get3() */
|
714
|
+
LCB_CALLBACK_STORE, /**< lcb_store3() */
|
715
|
+
LCB_CALLBACK_COUNTER, /**< lcb_counter3() */
|
716
|
+
LCB_CALLBACK_TOUCH, /**< lcb_touch3() */
|
717
|
+
LCB_CALLBACK_REMOVE, /**< lcb_remove3() */
|
718
|
+
LCB_CALLBACK_UNLOCK, /**< lcb_unlock3() */
|
719
|
+
LCB_CALLBACK_STATS, /**< lcb_stats3() */
|
720
|
+
LCB_CALLBACK_VERSIONS, /**< lcb_server_versions3() */
|
721
|
+
LCB_CALLBACK_VERBOSITY, /**< lcb_server_verbosity3() */
|
722
|
+
LCB_CALLBACK_FLUSH, /**< lcb_flush3() */
|
723
|
+
LCB_CALLBACK_OBSERVE, /**< lcb_observe3_ctxnew() */
|
724
|
+
LCB_CALLBACK_GETREPLICA, /**< lcb_rget3() */
|
725
|
+
LCB_CALLBACK_ENDURE, /**< lcb_endure3_ctxnew() */
|
726
|
+
LCB_CALLBACK_HTTP, /**< lcb_http3() */
|
727
|
+
LCB_CALLBACK_CBFLUSH, /**< lcb_cbflush3() */
|
728
|
+
LCB_CALLBACK_OBSEQNO, /**< For lcb_observe_seqno3() */
|
729
|
+
LCB_CALLBACK_STOREDUR, /** <for lcb_storedur3() */
|
730
|
+
LCB_CALLBACK_SDLOOKUP,
|
731
|
+
LCB_CALLBACK_SDMUTATE,
|
732
|
+
LCB_CALLBACK_NOOP, /**< lcb_noop3() */
|
733
|
+
LCB_CALLBACK_PING, /**< lcb_ping3() */
|
734
|
+
LCB_CALLBACK_DIAG, /**< lcb_diag() */
|
735
|
+
LCB_CALLBACK__MAX /* Number of callbacks */
|
736
|
+
} lcb_CALLBACKTYPE;
|
737
|
+
|
738
|
+
/* The following callback types cannot be set using lcb_install_callback3(),
|
739
|
+
* however, their value is passed along as the second argument of their
|
740
|
+
* respective callbacks. This allows you to still use the same callback,
|
741
|
+
* differentiating their meaning by the type. */
|
742
|
+
|
743
|
+
/** Callback type for views (cannot be used for lcb_install_callback3()) */
|
744
|
+
#define LCB_CALLBACK_VIEWQUERY -1
|
745
|
+
|
746
|
+
/** Callback type for N1QL (cannot be used for lcb_install_callback3()) */
|
747
|
+
#define LCB_CALLBACK_N1QL -2
|
748
|
+
|
749
|
+
/** Callback type for N1QL index management (cannot be used for lcb_install_callback3()) */
|
750
|
+
#define LCB_CALLBACK_IXMGMT -3
|
751
|
+
|
752
|
+
/**
|
753
|
+
* Callback invoked for responses.
|
754
|
+
* @param instance The handle
|
755
|
+
* @param cbtype The type of callback - or in other words, the type of operation
|
756
|
+
* this callback has been invoked for.
|
757
|
+
* @param resp The response for the operation. Depending on the operation this
|
758
|
+
* response structure should be casted into a more specialized type.
|
759
|
+
*/
|
760
|
+
typedef void (*lcb_RESPCALLBACK)
|
761
|
+
(lcb_t instance, int cbtype, const lcb_RESPBASE* resp);
|
762
|
+
|
763
|
+
/**
|
764
|
+
* @committed
|
765
|
+
*
|
766
|
+
* Install a new-style callback for an operation. The callback will be invoked
|
767
|
+
* with the relevant response structure.
|
768
|
+
*
|
769
|
+
* @param instance the handle
|
770
|
+
* @param cbtype the type of operation for which this callback should be installed.
|
771
|
+
* The value should be one of the lcb_CALLBACKTYPE constants
|
772
|
+
* @param cb the callback to install
|
773
|
+
* @return the old callback
|
774
|
+
*
|
775
|
+
* @note LCB_CALLBACK_DEFAULT is initialized to the default handler which proxies
|
776
|
+
* back to the older 2.x callbacks. If you set `cbtype` to LCB_CALLBACK_DEFAULT
|
777
|
+
* then your `2.x` callbacks _will not work_.
|
778
|
+
*
|
779
|
+
* @note The old callback may be `NULL`. It is usually not an error to have a
|
780
|
+
* `NULL` callback installed. If the callback is `NULL`, then the default callback
|
781
|
+
* invocation pattern will take place (as desribed above). However it is an error
|
782
|
+
* to set the default callback to `NULL`.
|
783
|
+
*/
|
784
|
+
LIBCOUCHBASE_API
|
785
|
+
lcb_RESPCALLBACK
|
786
|
+
lcb_install_callback3(lcb_t instance, int cbtype, lcb_RESPCALLBACK cb);
|
787
|
+
|
788
|
+
/**
|
789
|
+
* @committed
|
790
|
+
*
|
791
|
+
* Get the current callback installed as `cbtype`. Note that this does not
|
792
|
+
* perform any kind of resolution (as described in lcb_install_callback3) and
|
793
|
+
* will only return a non-`NULL` value if a callback had specifically been
|
794
|
+
* installed via lcb_install_callback3() with the given `cbtype`.
|
795
|
+
*
|
796
|
+
* @param instance the handle
|
797
|
+
* @param cbtype the type of callback to retrieve
|
798
|
+
* @return the installed callback for the type.
|
799
|
+
*/
|
800
|
+
LIBCOUCHBASE_API
|
801
|
+
lcb_RESPCALLBACK
|
802
|
+
lcb_get_callback3(lcb_t instance, int cbtype);
|
803
|
+
|
804
|
+
/**
|
805
|
+
* Returns the type of the callback as a string.
|
806
|
+
* This function is helpful for debugging and demonstrative processes.
|
807
|
+
* @param cbtype the type of the callback (the second argument to the callback)
|
808
|
+
* @return a string describing the callback type
|
809
|
+
*/
|
810
|
+
LIBCOUCHBASE_API
|
811
|
+
const char *
|
812
|
+
lcb_strcbtype(int cbtype);
|
813
|
+
|
814
|
+
/**@}*/
|
815
|
+
|
816
|
+
/**
|
817
|
+
* @ingroup lcb-kv-api
|
818
|
+
* @defgroup lcb-get Read
|
819
|
+
* @brief Retrieve a document from the cluster
|
820
|
+
* @addtogroup lcb-get
|
821
|
+
* @{
|
822
|
+
*/
|
823
|
+
|
824
|
+
/**
|
825
|
+
* If this bit is set in lcb_CMDGET::cmdflags then the expiry time is cleared if
|
826
|
+
* lcb_CMDGET::exptime is 0. This allows get-and-touch with an expiry of 0.
|
827
|
+
*/
|
828
|
+
#define LCB_CMDGET_F_CLEAREXP (1<<16)
|
829
|
+
|
830
|
+
/**@brief Command for retrieving a single item
|
831
|
+
*
|
832
|
+
* @see lcb_get3()
|
833
|
+
* @see lcb_RESPGET
|
834
|
+
*
|
835
|
+
* @note The #cas member should be set to 0 for this operation. If the #cas is
|
836
|
+
* not 0, lcb_get3() will fail with ::LCB_OPTIONS_CONFLICT.
|
837
|
+
*
|
838
|
+
* ### Use of the `exptime` field
|
839
|
+
*
|
840
|
+
* <ul>
|
841
|
+
* <li>Get And Touch:
|
842
|
+
*
|
843
|
+
* It is possible to retrieve an item and concurrently modify its expiration
|
844
|
+
* time (thus keeping it "alive"). The item's expiry time can be set using
|
845
|
+
* the #exptime field.
|
846
|
+
* </li>
|
847
|
+
*
|
848
|
+
* <li>Lock
|
849
|
+
* If the #lock field is set to non-zero, the #exptime field indicates the amount
|
850
|
+
* of time the lock should be held for
|
851
|
+
* </li>
|
852
|
+
* </ul>
|
853
|
+
*/
|
854
|
+
typedef struct {
|
855
|
+
LCB_CMD_BASE;
|
856
|
+
/**If set to true, the `exptime` field inside `options` will take to mean
|
857
|
+
* the time the lock should be held. While the lock is held, other operations
|
858
|
+
* trying to access the key will fail with an `LCB_ETMPFAIL` error. The
|
859
|
+
* item may be unlocked either via `lcb_unlock3()` or via a mutation
|
860
|
+
* operation with a supplied CAS
|
861
|
+
*/
|
862
|
+
int lock;
|
863
|
+
} lcb_CMDGET;
|
864
|
+
|
865
|
+
/** @brief Response structure when retrieving a single item */
|
866
|
+
typedef struct {
|
867
|
+
LCB_RESP_BASE
|
868
|
+
const void *value; /**< Value buffer for the item */
|
869
|
+
lcb_SIZE nvalue; /**< Length of value */
|
870
|
+
void* bufh;
|
871
|
+
lcb_datatype_t datatype; /**< @internal */
|
872
|
+
lcb_U32 itmflags; /**< User-defined flags for the item */
|
873
|
+
} lcb_RESPGET;
|
874
|
+
|
875
|
+
/**
|
876
|
+
* @committed
|
877
|
+
*
|
878
|
+
* @brief Spool a single get operation
|
879
|
+
* @param instance the handle
|
880
|
+
* @param cookie a pointer to be associated with the command
|
881
|
+
* @param cmd the command structure
|
882
|
+
* @return LCB_SUCCESS if successful, an error code otherwise
|
883
|
+
*
|
884
|
+
* @par Request
|
885
|
+
* @code{.c}
|
886
|
+
* lcb_CMDGET cmd = { 0 };
|
887
|
+
* LCB_CMD_SET_KEY(&cmd, "Hello", 5);
|
888
|
+
* lcb_get3(instance, cookie, &cmd);
|
889
|
+
* @endcode
|
890
|
+
*
|
891
|
+
* @par Response
|
892
|
+
* @code{.c}
|
893
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_GET, get_callback);
|
894
|
+
* static void get_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb) {
|
895
|
+
* const lcb_RESPGET *resp = (const lcb_RESPGET*)rb;
|
896
|
+
* printf("Got response for key: %.*s\n", (int)resp->key, resp->nkey);
|
897
|
+
*
|
898
|
+
* if (resp->rc != LCB_SUCCESS) {
|
899
|
+
* printf("Couldn't get item: %s\n", lcb_strerror(NULL, resp->rc));
|
900
|
+
* } else {
|
901
|
+
* printf("Got value: %.*s\n", (int)resp->nvalue, resp->value);
|
902
|
+
* printf("Got CAS: 0x%llx\n", resp->cas);
|
903
|
+
* printf("Got item/formatting flags: 0x%x\n", resp->itmflags);
|
904
|
+
* }
|
905
|
+
* }
|
906
|
+
*
|
907
|
+
* @endcode
|
908
|
+
*
|
909
|
+
* @par Errors
|
910
|
+
* @cb_err ::LCB_KEY_ENOENT if the item does not exist in the cluster
|
911
|
+
* @cb_err ::LCB_ETMPFAIL if the lcb_CMDGET::lock option was set but the item
|
912
|
+
* was already locked. Note that this error may also be returned (as a generic
|
913
|
+
* error) if there is a resource constraint within the server itself.
|
914
|
+
*/
|
915
|
+
LIBCOUCHBASE_API
|
916
|
+
lcb_error_t
|
917
|
+
lcb_get3(lcb_t instance, const void *cookie, const lcb_CMDGET *cmd);
|
918
|
+
/**@}*/
|
919
|
+
|
920
|
+
/**
|
921
|
+
* @ingroup lcb-kv-api
|
922
|
+
* @defgroup lcb-get-replica Read (Replica)
|
923
|
+
* @brief Retrieve a document from a replica if it cannot be fetched from the
|
924
|
+
* primary
|
925
|
+
* @addtogroup lcb-get-replica
|
926
|
+
* @{
|
927
|
+
*/
|
928
|
+
|
929
|
+
|
930
|
+
/**@brief Select get-replica mode
|
931
|
+
* @see lcb_rget3_cmd_t */
|
932
|
+
typedef enum {
|
933
|
+
/**Query all the replicas sequentially, retrieving the first successful
|
934
|
+
* response */
|
935
|
+
LCB_REPLICA_FIRST = 0x00,
|
936
|
+
|
937
|
+
/**Query all the replicas concurrently, retrieving all the responses*/
|
938
|
+
LCB_REPLICA_ALL = 0x01,
|
939
|
+
|
940
|
+
/**Query the specific replica specified by the
|
941
|
+
* lcb_rget3_cmd_t#index field */
|
942
|
+
LCB_REPLICA_SELECT = 0x02
|
943
|
+
} lcb_replica_t;
|
944
|
+
|
945
|
+
/**
|
946
|
+
* @brief Command for requesting an item from a replica
|
947
|
+
* @note The `options.exptime` and `options.cas` fields are ignored for this
|
948
|
+
* command.
|
949
|
+
*
|
950
|
+
* This structure is similar to @ref lcb_RESPGET with the addition of an
|
951
|
+
* `index` and `strategy` field which allow you to control and select how
|
952
|
+
* many replicas are queried.
|
953
|
+
*
|
954
|
+
* @see lcb_rget3(), lcb_RESPGET
|
955
|
+
*/
|
956
|
+
typedef struct {
|
957
|
+
LCB_CMD_BASE;
|
958
|
+
/**
|
959
|
+
* Strategy for selecting a replica. The default is ::LCB_REPLICA_FIRST
|
960
|
+
* which results in the client trying each replica in sequence until a
|
961
|
+
* successful reply is found, and returned in the callback.
|
962
|
+
*
|
963
|
+
* ::LCB_REPLICA_FIRST evaluates to 0.
|
964
|
+
*
|
965
|
+
* Other options include:
|
966
|
+
* <ul>
|
967
|
+
* <li>::LCB_REPLICA_ALL - queries all replicas concurrently and dispatches
|
968
|
+
* a callback for each reply</li>
|
969
|
+
* <li>::LCB_REPLICA_SELECT - queries a specific replica indicated in the
|
970
|
+
* #index field</li>
|
971
|
+
* </ul>
|
972
|
+
*
|
973
|
+
* @note When ::LCB_REPLICA_ALL is selected, the callback will be invoked
|
974
|
+
* multiple times, one for each replica. The final callback will have the
|
975
|
+
* ::LCB_RESP_F_FINAL bit set in the lcb_RESPBASE::rflags field. The final
|
976
|
+
* response will also contain the response from the last replica to
|
977
|
+
* respond.
|
978
|
+
*/
|
979
|
+
lcb_replica_t strategy;
|
980
|
+
|
981
|
+
/**
|
982
|
+
* Valid only when #strategy is ::LCB_REPLICA_SELECT, specifies the replica
|
983
|
+
* index number to query. This should be no more than `nreplicas-1`
|
984
|
+
* where `nreplicas` is the number of replicas the bucket is configured with.
|
985
|
+
*/
|
986
|
+
int index;
|
987
|
+
} lcb_CMDGETREPLICA;
|
988
|
+
|
989
|
+
/**@committed
|
990
|
+
*
|
991
|
+
* @brief Spool a single get-with-replica request
|
992
|
+
* @param instance
|
993
|
+
* @param cookie
|
994
|
+
* @param cmd
|
995
|
+
* @return LCB_SUCCESS on success, error code otherwise.
|
996
|
+
*
|
997
|
+
* When a response is received, the callback installed for ::LCB_CALLBACK_GETREPLICA
|
998
|
+
* will be invoked. The response will be an @ref lcb_RESPGET pointer.
|
999
|
+
*
|
1000
|
+
* ### Request
|
1001
|
+
* @code{.c}
|
1002
|
+
* lcb_CMDGETREPLICA cmd = { 0 };
|
1003
|
+
* LCB_CMD_SET_KEY(&cmd, "key", 3);
|
1004
|
+
* lcb_rget3(instance, cookie, &cmd);
|
1005
|
+
* @endcode
|
1006
|
+
*
|
1007
|
+
* ### Response
|
1008
|
+
* @code{.c}
|
1009
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_GETREPLICA, rget_callback);
|
1010
|
+
* static void rget_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
|
1011
|
+
* {
|
1012
|
+
* const lcb_RESPGET *resp = (const lcb_RESPGET *)rb;
|
1013
|
+
* printf("Got Get-From-Replica response for %.*s\n", (int)resp->key, resp->nkey);
|
1014
|
+
* if (resp->rc == LCB_SUCCESS) {
|
1015
|
+
* printf("Got response: %.*s\n", (int)resp->value, resp->nvalue);
|
1016
|
+
* else {
|
1017
|
+
* printf("Couldn't retrieve: %s\n", lcb_strerror(NULL, resp->rc));
|
1018
|
+
* }
|
1019
|
+
* }
|
1020
|
+
* @endcode
|
1021
|
+
*
|
1022
|
+
* @warning As this function queries a replica node for data it is possible
|
1023
|
+
* that the returned document may not reflect the latest document in the server.
|
1024
|
+
*
|
1025
|
+
* @warning This function should only be used in cases where a normal lcb_get3()
|
1026
|
+
* has failed, or where there is reason to believe it will fail. Because this
|
1027
|
+
* function may query more than a single replica it may cause additional network
|
1028
|
+
* and server-side CPU load. Use sparingly and only when necessary.
|
1029
|
+
*
|
1030
|
+
* @cb_err ::LCB_KEY_ENOENT if the key is not found on the replica(s),
|
1031
|
+
* ::LCB_NO_MATCHING_SERVER if there are no replicas (either configured or online),
|
1032
|
+
* or if the given replica
|
1033
|
+
* (if lcb_CMDGETREPLICA::strategy is ::LCB_REPLICA_SELECT) is not available or
|
1034
|
+
* is offline.
|
1035
|
+
*/
|
1036
|
+
LIBCOUCHBASE_API
|
1037
|
+
lcb_error_t
|
1038
|
+
lcb_rget3(lcb_t instance, const void *cookie, const lcb_CMDGETREPLICA *cmd);
|
1039
|
+
/**@}*/
|
1040
|
+
|
1041
|
+
/**
|
1042
|
+
* @ingroup lcb-kv-api
|
1043
|
+
* @defgroup lcb-store Create/Update
|
1044
|
+
* @brief Set the value of a document
|
1045
|
+
* @addtogroup lcb-store
|
1046
|
+
* @{
|
1047
|
+
*/
|
1048
|
+
|
1049
|
+
/**
|
1050
|
+
* @brief Values for lcb_CMDSTORE::operation
|
1051
|
+
*
|
1052
|
+
* Storing an item in couchbase is only one operation with a different
|
1053
|
+
* set of attributes / constraints.
|
1054
|
+
*/
|
1055
|
+
typedef enum {
|
1056
|
+
/**
|
1057
|
+
* Will cause the operation to fail if the key already exists in the
|
1058
|
+
* cluster.
|
1059
|
+
*/
|
1060
|
+
LCB_ADD = 0x01,
|
1061
|
+
|
1062
|
+
/**
|
1063
|
+
* Will cause the operation to fail _unless_ the key already exists in the
|
1064
|
+
* cluster.
|
1065
|
+
*/
|
1066
|
+
LCB_REPLACE = 0x02,
|
1067
|
+
|
1068
|
+
/** Unconditionally store the item in the cluster */
|
1069
|
+
LCB_SET = 0x03,
|
1070
|
+
|
1071
|
+
/**
|
1072
|
+
* The default storage mode. This constant was added in version 2.6.2 for
|
1073
|
+
* the sake of maintaining a default storage mode, eliminating the need
|
1074
|
+
* for simple storage operations to explicitly define
|
1075
|
+
* lcb_CMDSTORE::operation. Behaviorally it is identical to @ref LCB_SET
|
1076
|
+
* in that it will make the server unconditionally store the item, whether
|
1077
|
+
* it exists or not.
|
1078
|
+
*/
|
1079
|
+
LCB_UPSERT = 0x00,
|
1080
|
+
|
1081
|
+
/**
|
1082
|
+
* Rather than setting the contents of the entire document, take the value
|
1083
|
+
* specified in lcb_CMDSTORE::value and _append_ it to the existing bytes in
|
1084
|
+
* the value.
|
1085
|
+
*/
|
1086
|
+
LCB_APPEND = 0x04,
|
1087
|
+
|
1088
|
+
/**
|
1089
|
+
* Like ::LCB_APPEND, but prepends the new value to the existing value.
|
1090
|
+
*/
|
1091
|
+
LCB_PREPEND = 0x05
|
1092
|
+
} lcb_storage_t;
|
1093
|
+
|
1094
|
+
/**@brief
|
1095
|
+
*
|
1096
|
+
* Command for storing an item to the server. This command must contain the
|
1097
|
+
* key to mutate, the value which should be set (or appended/prepended) in the
|
1098
|
+
* lcb_CMDSTORE::value field (see LCB_CMD_SET_VALUE()) and the operation indicating
|
1099
|
+
* the mutation type (lcb_CMDSTORE::operation).
|
1100
|
+
*
|
1101
|
+
* @warning #exptime *cannot* be used with #operation set to @ref LCB_APPEND
|
1102
|
+
* or @ref LCB_PREPEND.
|
1103
|
+
*/
|
1104
|
+
typedef struct {
|
1105
|
+
LCB_CMD_BASE;
|
1106
|
+
|
1107
|
+
/**
|
1108
|
+
* Value to store on the server. The value may be set using the
|
1109
|
+
* LCB_CMD_SET_VALUE() or LCB_CMD_SET_VALUEIOV() API
|
1110
|
+
*/
|
1111
|
+
lcb_VALBUF value;
|
1112
|
+
|
1113
|
+
/**
|
1114
|
+
* Format flags used by clients to determine the underlying encoding of
|
1115
|
+
* the value. This value is also returned during retrieval operations in the
|
1116
|
+
* lcb_RESPGET::itmflags field
|
1117
|
+
*/
|
1118
|
+
lcb_U32 flags;
|
1119
|
+
|
1120
|
+
/** Do not set this value for now */
|
1121
|
+
lcb_datatype_t datatype;
|
1122
|
+
|
1123
|
+
/** Controls *how* the operation is perfomed. See the documentation for
|
1124
|
+
* @ref lcb_storage_t for the options. There is no default value for this
|
1125
|
+
* field.
|
1126
|
+
*/
|
1127
|
+
lcb_storage_t operation;
|
1128
|
+
} lcb_CMDSTORE;
|
1129
|
+
|
1130
|
+
/**
|
1131
|
+
* @brief Response structure for lcb_store3()
|
1132
|
+
*/
|
1133
|
+
typedef struct {
|
1134
|
+
LCB_RESP_BASE
|
1135
|
+
|
1136
|
+
/** The type of operation which was performed */
|
1137
|
+
lcb_storage_t op;
|
1138
|
+
} lcb_RESPSTORE;
|
1139
|
+
|
1140
|
+
/**
|
1141
|
+
* @committed
|
1142
|
+
*
|
1143
|
+
* @brief Set the value buffer for the command. This may be used when the new
|
1144
|
+
* value is a single contiguous buffer.
|
1145
|
+
*
|
1146
|
+
* @param scmd an lcb_CMDSTORE pointer
|
1147
|
+
* @param valbuf the buffer for the value
|
1148
|
+
* @param vallen the length of the buffer
|
1149
|
+
*
|
1150
|
+
* The buffer needs to remain valid only until the command is passed to the
|
1151
|
+
* lcb_store3() function.
|
1152
|
+
*/
|
1153
|
+
#define LCB_CMD_SET_VALUE(scmd, valbuf, vallen) do { \
|
1154
|
+
(scmd)->value.vtype = LCB_KV_COPY; \
|
1155
|
+
(scmd)->value.u_buf.contig.bytes = valbuf; \
|
1156
|
+
(scmd)->value.u_buf.contig.nbytes = vallen; \
|
1157
|
+
} while (0);
|
1158
|
+
|
1159
|
+
/**
|
1160
|
+
* @committed
|
1161
|
+
*
|
1162
|
+
* @brief Set value from a series of input buffers. This may be used when the
|
1163
|
+
* input buffer is not contiguous. Using this call eliminates the need for
|
1164
|
+
* creating a temporary contiguous buffer in which to store the value.
|
1165
|
+
*
|
1166
|
+
* @param scmd the command which needs a value
|
1167
|
+
* @param iovs an array of @ref lcb_IOV structures
|
1168
|
+
* @param niovs number of items in the array.
|
1169
|
+
*
|
1170
|
+
* The buffers (and the IOV array itself)
|
1171
|
+
* need to remain valid only until the scheduler function is called. Once the
|
1172
|
+
* scheduling function is called, the buffer contents are copied into the
|
1173
|
+
* library's internal buffers.
|
1174
|
+
*/
|
1175
|
+
#define LCB_CMD_SET_VALUEIOV(scmd, iovs, niovs) do { \
|
1176
|
+
(scmd)->value.vtype = LCB_KV_IOVCOPY; \
|
1177
|
+
(scmd)->value.u_buf.multi.iov = iovs; \
|
1178
|
+
(scmd)->value.u_buf.multi.niov = niovs; \
|
1179
|
+
} while (0);
|
1180
|
+
|
1181
|
+
/**
|
1182
|
+
* @committed
|
1183
|
+
* @brief Schedule a single storage request
|
1184
|
+
* @param instance the handle
|
1185
|
+
* @param cookie pointer to associate with the command
|
1186
|
+
* @param cmd the command structure
|
1187
|
+
* @return LCB_SUCCESS on success, error code on failure
|
1188
|
+
*
|
1189
|
+
* ### Request
|
1190
|
+
*
|
1191
|
+
* @code{.c}
|
1192
|
+
* lcb_CMDSTORE cmd = { 0 };
|
1193
|
+
* LCB_CMD_SET_KEY(&cmd, "Key", 3);
|
1194
|
+
* LCB_CMD_SET_VALUE(&cmd, "value", 5);
|
1195
|
+
* cmd.operation = LCB_ADD; // Only create if it does not exist
|
1196
|
+
* cmd.exptime = 60; // expire in a minute
|
1197
|
+
* lcb_store3(instance, cookie, &cmd);
|
1198
|
+
* lcb_wait3(instance, LCB_WAIT_NOCHECK);
|
1199
|
+
* @endcode
|
1200
|
+
*
|
1201
|
+
* ### Response
|
1202
|
+
* @code{.c}
|
1203
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_STORE, store_callback);
|
1204
|
+
* void store_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
|
1205
|
+
* {
|
1206
|
+
* if (rb->rc == LCB_SUCCESS) {
|
1207
|
+
* printf("Store success: CAS=%llx\n", rb->cas);
|
1208
|
+
* } else {
|
1209
|
+
* printf("Store failed: %s\n", lcb_strerror(NULL, rb->rc);
|
1210
|
+
* }
|
1211
|
+
* }
|
1212
|
+
* @endcode
|
1213
|
+
*
|
1214
|
+
* Operation-specific error codes include:
|
1215
|
+
* @cb_err ::LCB_KEY_ENOENT if ::LCB_REPLACE was used and the key does not exist
|
1216
|
+
* @cb_err ::LCB_KEY_EEXISTS if ::LCB_ADD was used and the key already exists
|
1217
|
+
* @cb_err ::LCB_KEY_EEXISTS if the CAS was specified (for an operation other
|
1218
|
+
* than ::LCB_ADD) and the item exists on the server with a different
|
1219
|
+
* CAS
|
1220
|
+
* @cb_err ::LCB_KEY_EEXISTS if the item was locked and the CAS supplied did
|
1221
|
+
* not match the locked item's CAS (or if no CAS was supplied)
|
1222
|
+
* @cb_err ::LCB_NOT_STORED if an ::LCB_APPEND or ::LCB_PREPEND operation was
|
1223
|
+
* performed and the item did not exist on the server.
|
1224
|
+
* @cb_err ::LCB_E2BIG if the size of the value exceeds the cluster per-item
|
1225
|
+
* value limit (currently 20MB).
|
1226
|
+
*
|
1227
|
+
*
|
1228
|
+
* @note After a successful store operation you can use lcb_endure3_ctxnew()
|
1229
|
+
* to wait for the item to be persisted and/or replicated to other nodes.
|
1230
|
+
*/
|
1231
|
+
LIBCOUCHBASE_API
|
1232
|
+
lcb_error_t
|
1233
|
+
lcb_store3(lcb_t instance, const void *cookie, const lcb_CMDSTORE *cmd);
|
1234
|
+
/**@}*/
|
1235
|
+
|
1236
|
+
/**
|
1237
|
+
* @ingroup lcb-kv-api
|
1238
|
+
* @defgroup lcb-remove Delete
|
1239
|
+
* @brief Remove documents from the cluster
|
1240
|
+
* @addtogroup lcb-remove
|
1241
|
+
* @{
|
1242
|
+
*/
|
1243
|
+
|
1244
|
+
/**@brief
|
1245
|
+
* Command for removing an item from the server
|
1246
|
+
* @note The lcb_CMDREMOVE::exptime field here does nothing.
|
1247
|
+
*
|
1248
|
+
* The lcb_CMDREMOVE::cas field may be
|
1249
|
+
* set to the last CAS received from a previous operation if you wish to
|
1250
|
+
* ensure the item is removed only if it has not been mutated since the last
|
1251
|
+
* retrieval
|
1252
|
+
*/
|
1253
|
+
typedef lcb_CMDBASE lcb_CMDREMOVE;
|
1254
|
+
|
1255
|
+
/**@brief
|
1256
|
+
* Response structure for removal operation. The lcb_RESPREMOVE::cas field
|
1257
|
+
* may be used to check that it no longer exists on any node's storage
|
1258
|
+
* using the lcb_endure3_ctxnew() function. You can also use the
|
1259
|
+
* @ref lcb_MUTATION_TOKEN (via lcb_resp_get_mutation_token)
|
1260
|
+
*
|
1261
|
+
* The lcb_RESPREMOVE::rc field may be set to ::LCB_KEY_ENOENT if the item does
|
1262
|
+
* not exist, or ::LCB_KEY_EEXISTS if a CAS was specified and the item has since
|
1263
|
+
* been mutated.
|
1264
|
+
*/
|
1265
|
+
typedef lcb_RESPBASE lcb_RESPREMOVE;
|
1266
|
+
|
1267
|
+
/**@committed
|
1268
|
+
* @brief Spool a removal of an item
|
1269
|
+
* @param instance the handle
|
1270
|
+
* @param cookie pointer to associate with the request
|
1271
|
+
* @param cmd the command
|
1272
|
+
* @return LCB_SUCCESS on success, other code on failure
|
1273
|
+
*
|
1274
|
+
* ### Request
|
1275
|
+
* @code{.c}
|
1276
|
+
* lcb_CMDREMOVE cmd = { 0 };
|
1277
|
+
* LCB_CMD_SET_KEY(&cmd, "deleteme", strlen("deleteme"));
|
1278
|
+
* lcb_remove3(instance, cookie, &cmd);
|
1279
|
+
* @endcode
|
1280
|
+
*
|
1281
|
+
* ### Response
|
1282
|
+
* @code{.c}
|
1283
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_REMOVE, rm_callback);
|
1284
|
+
* void rm_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
|
1285
|
+
* {
|
1286
|
+
* printf("Key: %.*s...", (int)resp->nkey, resp->key);
|
1287
|
+
* if (rb->rc != LCB_SUCCESS) {
|
1288
|
+
* printf("Failed to remove item!: %s\n", lcb_strerror(NULL, rb->rc));
|
1289
|
+
* } else {
|
1290
|
+
* printf("Removed item!\n");
|
1291
|
+
* }
|
1292
|
+
* }
|
1293
|
+
* @endcode
|
1294
|
+
*
|
1295
|
+
* The following operation-specific error codes are returned in the callback
|
1296
|
+
* @cb_err ::LCB_KEY_ENOENT if the key does not exist
|
1297
|
+
* @cb_err ::LCB_KEY_EEXISTS if the CAS was specified and it does not match the
|
1298
|
+
* CAS on the server
|
1299
|
+
* @cb_err ::LCB_KEY_EEXISTS if the item was locked and no CAS (or an incorrect
|
1300
|
+
* CAS) was specified.
|
1301
|
+
*
|
1302
|
+
*/
|
1303
|
+
LIBCOUCHBASE_API
|
1304
|
+
lcb_error_t
|
1305
|
+
lcb_remove3(lcb_t instance, const void *cookie, const lcb_CMDREMOVE * cmd);
|
1306
|
+
/**@}*/
|
1307
|
+
|
1308
|
+
/**
|
1309
|
+
* @ingroup lcb-kv-api
|
1310
|
+
* @defgroup lcb-mctx MULTICMD API
|
1311
|
+
* @addtogroup lcb-mctx
|
1312
|
+
* @{
|
1313
|
+
*/
|
1314
|
+
/**
|
1315
|
+
* Multi Command Context API
|
1316
|
+
* Some commands (notably, OBSERVE and its higher level equivalent, endue)
|
1317
|
+
* are handled more efficiently at the cluster side by stuffing multiple
|
1318
|
+
* items into a single packet.
|
1319
|
+
*
|
1320
|
+
* This structure defines three function pointers to invoke. The #addcmd()
|
1321
|
+
* function will add a new command to the current packet, the #done()
|
1322
|
+
* function will schedule the packet(s) into the current scheduling context
|
1323
|
+
* and the #fail() function will destroy the context without progressing
|
1324
|
+
* further.
|
1325
|
+
*
|
1326
|
+
* Some commands will return an lcb_MULTICMD_CTX object to be used for this
|
1327
|
+
* purpose:
|
1328
|
+
*
|
1329
|
+
* @code{.c}
|
1330
|
+
* lcb_MUTLICMD_CTX *ctx = lcb_observe3_ctxnew(instance);
|
1331
|
+
*
|
1332
|
+
* lcb_CMDOBSERVE cmd = { 0 };
|
1333
|
+
* LCB_CMD_SET_KEY(&cmd, "key1", strlen("key1"));
|
1334
|
+
* ctx->addcmd(ctx, &cmd);
|
1335
|
+
* LCB_CMD_SET_KEY(&cmd.key, "key2", strlen("key2"));
|
1336
|
+
* ctx->addcmd(ctx, &cmd);
|
1337
|
+
* LCB_CMD_SET_KEY(&cmd.key, "key3", strlen("key3"));
|
1338
|
+
* ctx->addcmd(ctx, &cmd);
|
1339
|
+
*
|
1340
|
+
* ctx->done(ctx);
|
1341
|
+
* lcb_wait(instance);
|
1342
|
+
* @endcode
|
1343
|
+
*/
|
1344
|
+
typedef struct lcb_MULTICMD_CTX_st {
|
1345
|
+
/**
|
1346
|
+
* Add a command to the current context
|
1347
|
+
* @param ctx the context
|
1348
|
+
* @param cmd the command to add. Note that `cmd` may be a subclass of lcb_CMDBASE
|
1349
|
+
* @return LCB_SUCCESS, or failure if a command could not be added.
|
1350
|
+
*/
|
1351
|
+
lcb_error_t (*addcmd)(struct lcb_MULTICMD_CTX_st *ctx, const lcb_CMDBASE *cmd);
|
1352
|
+
|
1353
|
+
/**
|
1354
|
+
* Indicate that no more commands are added to this context, and that the
|
1355
|
+
* context should assemble the packets and place them in the current
|
1356
|
+
* scheduling context
|
1357
|
+
* @param ctx The multi context
|
1358
|
+
* @param cookie The cookie for all commands
|
1359
|
+
* @return LCB_SUCCESS if scheduled successfully, or an error code if there
|
1360
|
+
* was a problem constructing the packet(s).
|
1361
|
+
*/
|
1362
|
+
lcb_error_t (*done)(struct lcb_MULTICMD_CTX_st *ctx, const void *cookie);
|
1363
|
+
|
1364
|
+
/**
|
1365
|
+
* Indicate that no more commands should be added to this context, and that
|
1366
|
+
* the context should not add its contents to the packet queues, but rather
|
1367
|
+
* release its resources. Called if you don't want to actually perform
|
1368
|
+
* the operations.
|
1369
|
+
* @param ctx
|
1370
|
+
*/
|
1371
|
+
void (*fail)(struct lcb_MULTICMD_CTX_st *ctx);
|
1372
|
+
|
1373
|
+
#ifdef LCB_TRACING
|
1374
|
+
/**
|
1375
|
+
* Associate parent tracing span with the group operation
|
1376
|
+
*
|
1377
|
+
* @param ctx The multi context
|
1378
|
+
* @param span Parent span
|
1379
|
+
*/
|
1380
|
+
void (*setspan)(struct lcb_MULTICMD_CTX_st *ctx, lcbtrace_SPAN *span);
|
1381
|
+
#endif
|
1382
|
+
} lcb_MULTICMD_CTX;
|
1383
|
+
/**@}*/
|
1384
|
+
|
1385
|
+
/**
|
1386
|
+
* @ingroup lcb-kv-api
|
1387
|
+
* @defgroup lcb-durability Durability
|
1388
|
+
* @brief Ensure persistence and mutation of documents
|
1389
|
+
* @addtogroup lcb-durability
|
1390
|
+
* @{
|
1391
|
+
*/
|
1392
|
+
|
1393
|
+
/**
|
1394
|
+
* @name Wait for a mutation to be persisted/replicated
|
1395
|
+
* @{
|
1396
|
+
*/
|
1397
|
+
|
1398
|
+
/**
|
1399
|
+
* Type of durability polling to use.
|
1400
|
+
*/
|
1401
|
+
typedef enum {
|
1402
|
+
/**
|
1403
|
+
* Use the preferred durability. If ::LCB_CNTL_FETCH_MUTATION_TOKENS is
|
1404
|
+
* enabled and the server version is 4.0 or greater then ::LCB_DURABILITY_MODE_SEQNO
|
1405
|
+
* is used. Otherwise ::LCB_DURABILITY_MODE_CAS is used.
|
1406
|
+
*/
|
1407
|
+
LCB_DURABILITY_MODE_DEFAULT = 0,
|
1408
|
+
|
1409
|
+
/**
|
1410
|
+
* Explicitly request CAS-based durability. This is done by checking the
|
1411
|
+
* CAS of the item on each server with the item specified in the input.
|
1412
|
+
* The durability operation is considered complete when all items' CAS
|
1413
|
+
* values match. If the CAS value on the master node changes then the
|
1414
|
+
* durability operation will fail with ::LCB_KEY_EEXISTS.
|
1415
|
+
*
|
1416
|
+
* @note
|
1417
|
+
* CAS may change either because of a failover or because of another
|
1418
|
+
* subsequent mutation. These scenarios are possible (though unlikely).
|
1419
|
+
* The ::LCB_DURABILITY_MODE_SEQNO mode is not subject to these constraints.
|
1420
|
+
*/
|
1421
|
+
LCB_DURABILITY_MODE_CAS,
|
1422
|
+
|
1423
|
+
/**
|
1424
|
+
* Use sequence-number based polling. This is done by checking the current
|
1425
|
+
* "mutation sequence number" for the given mutation. To use this mode
|
1426
|
+
* either an explicit @ref lcb_MUTATION_TOKEN needs to be passed, or
|
1427
|
+
* the ::LCB_CNTL_DURABILITY_MUTATION_TOKENS should be set, allowing
|
1428
|
+
* the caching of the latest mutation token for each vBucket.
|
1429
|
+
*/
|
1430
|
+
LCB_DURABILITY_MODE_SEQNO
|
1431
|
+
} lcb_DURMODE;
|
1432
|
+
|
1433
|
+
/** @brief Options for lcb_endure3_ctxnew() */
|
1434
|
+
typedef struct {
|
1435
|
+
/**
|
1436
|
+
* Upper limit in microseconds from the scheduling of the command. When
|
1437
|
+
* this timeout occurs, all remaining non-verified keys will have their
|
1438
|
+
* callbacks invoked with @ref LCB_ETIMEDOUT.
|
1439
|
+
*
|
1440
|
+
* If this field is not set, the value of @ref LCB_CNTL_DURABILITY_TIMEOUT
|
1441
|
+
* will be used.
|
1442
|
+
*/
|
1443
|
+
lcb_U32 timeout;
|
1444
|
+
|
1445
|
+
/**
|
1446
|
+
* The durability check may involve more than a single call to observe - or
|
1447
|
+
* more than a single packet sent to a server to check the key status. This
|
1448
|
+
* value determines the time to wait (in microseconds)
|
1449
|
+
* between multiple probes for the same server.
|
1450
|
+
* If not set, the @ref LCB_CNTL_DURABILITY_INTERVAL will be used
|
1451
|
+
* instead.
|
1452
|
+
*/
|
1453
|
+
lcb_U32 interval;
|
1454
|
+
|
1455
|
+
/**
|
1456
|
+
* how many nodes the key should be persisted to (including master).
|
1457
|
+
* If set to 0 then persistence will not be checked. If set to a large
|
1458
|
+
* number (i.e. UINT16_MAX) and #cap_max is also set, will be set to the
|
1459
|
+
* maximum number of nodes to which persistence is possible (which will
|
1460
|
+
* always contain at least the master node).
|
1461
|
+
*
|
1462
|
+
* The maximum valid value for this field is
|
1463
|
+
* 1 + the total number of configured replicas for the bucket which are part
|
1464
|
+
* of the cluster. If this number is higher then it will either be
|
1465
|
+
* automatically capped to the maximum available if (#cap_max is set) or
|
1466
|
+
* will result in an ::LCB_DURABILITY_ETOOMANY error.
|
1467
|
+
*/
|
1468
|
+
lcb_U16 persist_to;
|
1469
|
+
|
1470
|
+
/**
|
1471
|
+
* how many nodes the key should be persisted to (excluding master).
|
1472
|
+
* If set to 0 then replication will not be checked. If set to a large
|
1473
|
+
* number (i.e. UINT16_MAX) and #cap_max is also set, will be set to the
|
1474
|
+
* maximum number of nodes to which replication is possible (which may
|
1475
|
+
* be 0 if the bucket is not configured for replicas).
|
1476
|
+
*
|
1477
|
+
* The maximum valid value for this field is the total number of configured
|
1478
|
+
* replicas which are part of the cluster. If this number is higher then
|
1479
|
+
* it will either be automatically capped to the maximum available
|
1480
|
+
* if (#cap_max is set) or will result in an ::LCB_DURABILITY_ETOOMANY
|
1481
|
+
* error.
|
1482
|
+
* */
|
1483
|
+
lcb_U16 replicate_to;
|
1484
|
+
|
1485
|
+
/**
|
1486
|
+
* this flag inverts the sense of the durability check and ensures that
|
1487
|
+
* the key does *not* exist. This should be used if checking durability
|
1488
|
+
* after an lcb_remove3() operation.
|
1489
|
+
*/
|
1490
|
+
lcb_U8 check_delete;
|
1491
|
+
|
1492
|
+
/**
|
1493
|
+
* If replication/persistence requirements are excessive, cap to
|
1494
|
+
* the maximum available
|
1495
|
+
*/
|
1496
|
+
lcb_U8 cap_max;
|
1497
|
+
|
1498
|
+
/**
|
1499
|
+
* Set the polling method to use.
|
1500
|
+
* The value for this field should be one of the @ref lcb_DURMODE constants.
|
1501
|
+
*/
|
1502
|
+
lcb_U8 pollopts;
|
1503
|
+
} lcb_DURABILITYOPTSv0;
|
1504
|
+
|
1505
|
+
/**@brief Options for lcb_endure3_ctxnew() (wrapper)
|
1506
|
+
* @see lcb_DURABILITYOPTSv0 */
|
1507
|
+
typedef struct lcb_durability_opts_st {
|
1508
|
+
int version;
|
1509
|
+
union {
|
1510
|
+
lcb_DURABILITYOPTSv0 v0;
|
1511
|
+
} v;
|
1512
|
+
} lcb_durability_opts_t;
|
1513
|
+
|
1514
|
+
/**Must specify this flag if using the 'mutation_token' field, as it was added in
|
1515
|
+
* a later version */
|
1516
|
+
#define LCB_CMDENDURE_F_MUTATION_TOKEN (1 << 16)
|
1517
|
+
|
1518
|
+
/**@brief Command structure for endure.
|
1519
|
+
* If the lcb_CMDENDURE::cas field is specified, the operation will check and
|
1520
|
+
* verify that the CAS found on each of the nodes matches the CAS specified
|
1521
|
+
* and only then consider the item to be replicated and/or persisted to the
|
1522
|
+
* nodes. If the item exists on the master's cache with a different CAS then
|
1523
|
+
* the operation will fail
|
1524
|
+
*/
|
1525
|
+
typedef struct {
|
1526
|
+
LCB_CMD_BASE;
|
1527
|
+
const lcb_MUTATION_TOKEN *mutation_token;
|
1528
|
+
} lcb_CMDENDURE;
|
1529
|
+
|
1530
|
+
/**@brief Response structure for endure */
|
1531
|
+
typedef struct {
|
1532
|
+
LCB_RESP_BASE
|
1533
|
+
/**
|
1534
|
+
* Total number of polls (i.e. how many packets per server) did this
|
1535
|
+
* operation require
|
1536
|
+
*/
|
1537
|
+
lcb_U16 nresponses;
|
1538
|
+
|
1539
|
+
/**
|
1540
|
+
* Whether this item exists in the master in its current form. This can be
|
1541
|
+
* true even if #rc is not successful
|
1542
|
+
*/
|
1543
|
+
lcb_U8 exists_master;
|
1544
|
+
|
1545
|
+
/**
|
1546
|
+
* True if item was persisted on the master node. This may be true even if
|
1547
|
+
* #rc is not successful.
|
1548
|
+
*/
|
1549
|
+
lcb_U8 persisted_master;
|
1550
|
+
|
1551
|
+
/**
|
1552
|
+
* Total number of nodes (including master) on which this mutation has
|
1553
|
+
* been persisted. Valid even if #rc is not successful.
|
1554
|
+
*/
|
1555
|
+
lcb_U8 npersisted;
|
1556
|
+
|
1557
|
+
/**
|
1558
|
+
* Total number of replica nodes to which this mutation has been replicated.
|
1559
|
+
* Valid even if #rc is not successful.
|
1560
|
+
*/
|
1561
|
+
lcb_U8 nreplicated;
|
1562
|
+
} lcb_RESPENDURE;
|
1563
|
+
|
1564
|
+
/**
|
1565
|
+
* @committed
|
1566
|
+
*
|
1567
|
+
* @details
|
1568
|
+
* Ensure a key is replicated to a set of nodes
|
1569
|
+
*
|
1570
|
+
* The lcb_endure3_ctxnew() API is used to wait asynchronously until the item
|
1571
|
+
* have been persisted and/or replicated to at least the number of nodes
|
1572
|
+
* specified in the durability options.
|
1573
|
+
*
|
1574
|
+
* The command is implemented by sending a series of `OBSERVE` broadcasts
|
1575
|
+
* (see lcb_observe3_ctxnew()) to all the nodes in the cluster which are either
|
1576
|
+
* master or replica for a specific key. It polls repeatedly
|
1577
|
+
* (see lcb_DURABILITYOPTSv0::interval) until all the items have been persisted and/or
|
1578
|
+
* replicated to the number of nodes specified in the criteria, or the timeout
|
1579
|
+
* (aee lcb_DURABILITYOPTsv0::timeout) has been reached.
|
1580
|
+
*
|
1581
|
+
* The lcb_DURABILITYOPTSv0::persist_to and lcb_DURABILITYOPTS::replicate_to
|
1582
|
+
* control the number of nodes the item must be persisted/replicated to
|
1583
|
+
* in order for the durability polling to succeed.
|
1584
|
+
*
|
1585
|
+
* @brief Return a new command context for scheduling endure operations
|
1586
|
+
* @param instance the instance
|
1587
|
+
* @param options a structure containing the various criteria needed for
|
1588
|
+
* durability requirements
|
1589
|
+
* @param[out] err Error code if a new context could not be created
|
1590
|
+
* @return the new context, or NULL on error. Note that in addition to memory
|
1591
|
+
* allocation failure, this function might also return NULL because the `options`
|
1592
|
+
* structure contained bad values. Always check the `err` result.
|
1593
|
+
*
|
1594
|
+
* @par Scheduling Errors
|
1595
|
+
* The following errors may be encountered when scheduling:
|
1596
|
+
*
|
1597
|
+
* @cb_err ::LCB_DURABILITY_ETOOMANY if either lcb_DURABILITYOPTS::persist_to or
|
1598
|
+
* lcb_DURABILITYOPTS::replicate_to is too big. `err` may indicate this.
|
1599
|
+
* @cb_err ::LCB_DURABILITY_NO_MUTATION_TOKENS if no relevant mutation token
|
1600
|
+
* could be found for a given command (this is returned from the relevant
|
1601
|
+
* lcb_MULTICMD_CTX::addcmd call).
|
1602
|
+
* @cb_err ::LCB_DUPLICATE_COMMANDS if using CAS-based durability and the
|
1603
|
+
* same key was submitted twice to lcb_MULTICMD_CTX::addcmd(). This error is
|
1604
|
+
* returned from lcb_MULTICMD_CTX::done()
|
1605
|
+
*
|
1606
|
+
* @par Callback Errors
|
1607
|
+
* The following errors may be returned in the callback:
|
1608
|
+
* @cb_err ::LCB_ETIMEDOUT if the criteria could not be verified within the
|
1609
|
+
* accepted timeframe (see lcb_DURABILITYOPTSv0::timeout)
|
1610
|
+
* @cb_err ::LCB_KEY_EEXISTS if using CAS-based durability and the item's
|
1611
|
+
* CAS has been changed on the master node
|
1612
|
+
* @cb_err ::LCB_MUTATION_LOST if using sequence-based durability and the
|
1613
|
+
* server has detected that data loss has occurred due to a failover.
|
1614
|
+
*
|
1615
|
+
* @par Creating request context
|
1616
|
+
* @code{.c}
|
1617
|
+
* lcb_durability_opts_t dopts;
|
1618
|
+
* lcb_error_t rc;
|
1619
|
+
* memset(&dopts, 0, sizeof dopts);
|
1620
|
+
* dopts.v.v0.persist_to = -1;
|
1621
|
+
* dopts.v.v0.replicate_to = -1;
|
1622
|
+
* dopts.v.v0.cap_max = 1;
|
1623
|
+
* mctx = lcb_endure3_ctxnew(instance, &dopts, &rc);
|
1624
|
+
* // Check mctx != NULL and rc == LCB_SUCCESS
|
1625
|
+
* @endcode
|
1626
|
+
*
|
1627
|
+
* @par Adding keys - CAS
|
1628
|
+
* This can be used to add keys using CAS-based durability. This shows an
|
1629
|
+
* example within a store callback.
|
1630
|
+
* @code{.c}
|
1631
|
+
* lcb_RESPSTORE *resp = get_store_response();
|
1632
|
+
* lcb_CMDENDURE cmd = { 0 };
|
1633
|
+
* LCB_CMD_SET_KEY(&cmd, resp->key, resp->nkey);
|
1634
|
+
* cmd.cas = resp->cas;
|
1635
|
+
* rc = mctx->addcmd(mctx, (const lcb_CMDBASE*)&cmd);
|
1636
|
+
* rc = mctx->done(mctx, cookie);
|
1637
|
+
* @endcode
|
1638
|
+
*
|
1639
|
+
* @par Adding keys - explicit sequence number
|
1640
|
+
* Shows how to use an explicit sequence number as a basis for polling
|
1641
|
+
* @code{.c}
|
1642
|
+
* // during instance creation:
|
1643
|
+
* lcb_cntl_string(instance, "fetch_mutation_tokens", "true");
|
1644
|
+
* lcb_connect(instance);
|
1645
|
+
* // ...
|
1646
|
+
* lcb_RESPSTORE *resp = get_store_response();
|
1647
|
+
* lcb_CMDENDURE cmd = { 0 };
|
1648
|
+
* LCB_CMD_SET_KEY(&cmd, resp->key, resp->nkey);
|
1649
|
+
* cmd.mutation_token = &resp->mutation_token;
|
1650
|
+
* cmd.cmdflags |= LCB_CMDENDURE_F_MUTATION_TOKEN;
|
1651
|
+
* rc = mctx->addcmd(mctx, (const lcb_CMDBASE*)&cmd);
|
1652
|
+
* rc = mctx->done(mctx, cookie);
|
1653
|
+
* @endcode
|
1654
|
+
*
|
1655
|
+
* @par Adding keys - implicit sequence number
|
1656
|
+
* Shows how to use an implicit mutation token (internally tracked by the
|
1657
|
+
* library) for durability:
|
1658
|
+
* @code{.c}
|
1659
|
+
* // during instance creation
|
1660
|
+
* lcb_cntl_string(instance, "fetch_mutation_tokens", "true");
|
1661
|
+
* lcb_cntl_string(instance, "dur_mutation_tokens", "true");
|
1662
|
+
* lcb_connect(instance);
|
1663
|
+
* // ...
|
1664
|
+
* lcb_CMDENDURE cmd = { 0 };
|
1665
|
+
* LCB_CMD_SET_KEY(&cmd, "key", strlen("key"));
|
1666
|
+
* mctx->addcmd(mctx, (const lcb_CMDBASE*)&cmd);
|
1667
|
+
* mctx->done(mctx, cookie);
|
1668
|
+
* @endcode
|
1669
|
+
*
|
1670
|
+
* @par Response
|
1671
|
+
* @code{.c}
|
1672
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_ENDURE, dur_callback);
|
1673
|
+
* void dur_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
|
1674
|
+
* {
|
1675
|
+
* const lcb_RESPENDURE *resp = (const lcb_RESPENDURE*)rb;
|
1676
|
+
* printf("Durability polling result for %.*s.. ", (int)resp->nkey, resp->key);
|
1677
|
+
* if (resp->rc != LCB_SUCCESS) {
|
1678
|
+
* printf("Failed: %s\n", lcb_strerror(NULL, resp->rc);
|
1679
|
+
* return;
|
1680
|
+
* }
|
1681
|
+
* }
|
1682
|
+
* @endcode
|
1683
|
+
*/
|
1684
|
+
LIBCOUCHBASE_API
|
1685
|
+
lcb_MULTICMD_CTX *
|
1686
|
+
lcb_endure3_ctxnew(lcb_t instance,
|
1687
|
+
const lcb_durability_opts_t *options, lcb_error_t *err);
|
1688
|
+
|
1689
|
+
/**
|
1690
|
+
* Command structure for lcb_storedur3()
|
1691
|
+
* This is much like @ref lcb_CMDSTORE, but also includes durability options.
|
1692
|
+
*/
|
1693
|
+
typedef struct {
|
1694
|
+
LCB_CMD_BASE;
|
1695
|
+
lcb_VALBUF value; /**< @see lcb_CMDSTORE::value */
|
1696
|
+
lcb_U32 flags; /**< @see lcb_CMDSTORE::flags */
|
1697
|
+
lcb_datatype_t datatype; /**< @internal */
|
1698
|
+
lcb_storage_t operation; /**< @see lcb_CMDSTORE::operation */
|
1699
|
+
|
1700
|
+
/**
|
1701
|
+
* Number of nodes to persist to. If negative, will be capped at the maximum
|
1702
|
+
* allowable for the current cluster.
|
1703
|
+
* @see lcb_DURABILITYOPTSv0::persist_to
|
1704
|
+
*/
|
1705
|
+
char persist_to;
|
1706
|
+
|
1707
|
+
/**
|
1708
|
+
* Number of nodes to replicate to. If negative, will be capped at the maximum
|
1709
|
+
* allowable for the current cluster.
|
1710
|
+
* @see lcb_DURABILITYOPTSv0::replicate_to
|
1711
|
+
*/
|
1712
|
+
char replicate_to;
|
1713
|
+
} lcb_CMDSTOREDUR;
|
1714
|
+
|
1715
|
+
/**
|
1716
|
+
* Response structure for `LCB_CALLBACK_STOREDUR.
|
1717
|
+
*/
|
1718
|
+
typedef struct {
|
1719
|
+
LCB_RESP_BASE
|
1720
|
+
/** Internal durability response structure. This should never be NULL */
|
1721
|
+
const lcb_RESPENDURE *dur_resp;
|
1722
|
+
|
1723
|
+
/**If the #rc field is not @ref LCB_SUCCESS, this field indicates
|
1724
|
+
* what failed. If this field is nonzero, then the store operation failed,
|
1725
|
+
* but the durability checking failed. If this field is zero then the
|
1726
|
+
* actual storage operation failed. */
|
1727
|
+
int store_ok;
|
1728
|
+
} lcb_RESPSTOREDUR;
|
1729
|
+
|
1730
|
+
/**
|
1731
|
+
* @volatile
|
1732
|
+
*
|
1733
|
+
* Schedule a storage operation with subsequent durability checking.
|
1734
|
+
*
|
1735
|
+
* This is a compound of a logical lcb_store3() followed by an
|
1736
|
+
* lcb_endure3_ctxnew() upon success.
|
1737
|
+
*/
|
1738
|
+
LIBCOUCHBASE_API
|
1739
|
+
lcb_error_t
|
1740
|
+
lcb_storedur3(lcb_t instance, const void *cookie, const lcb_CMDSTOREDUR *cmd);
|
1741
|
+
|
1742
|
+
#define LCB_DURABILITY_VALIDATE_CAPMAX (1 << 1)
|
1743
|
+
|
1744
|
+
/**
|
1745
|
+
* @committed
|
1746
|
+
*
|
1747
|
+
* Validate durability settings.
|
1748
|
+
*
|
1749
|
+
* This function will validate (and optionally modify) the settings. This is
|
1750
|
+
* helpful to ensure the durability options are valid _before_ issuing a command
|
1751
|
+
*
|
1752
|
+
* @param instance the instance
|
1753
|
+
*
|
1754
|
+
* @param[in,out] persist_to The desired number of servers to persist to.
|
1755
|
+
* If the `CAPMAX` flag is set, on output this will contain the effective
|
1756
|
+
* number of servers the item can be persisted to
|
1757
|
+
*
|
1758
|
+
* @param[in,out] replicate_to The desired number of servers to replicate to.
|
1759
|
+
* If the `CAPMAX` flag is set, on output this will contain the effective
|
1760
|
+
* number of servers the item can be replicated to
|
1761
|
+
*
|
1762
|
+
* @param options Options to use for validating. The only recognized option
|
1763
|
+
* is currently `LCB_DURABILITY_VALIDATE_CAPMAX` which has the same semantics
|
1764
|
+
* as lcb_DURABILITYOPTSv0::cap_max.
|
1765
|
+
*
|
1766
|
+
* @return LCB_SUCCESS on success
|
1767
|
+
* @return LCB_DURABILITY_ETOOMANY if the requirements exceed the number of
|
1768
|
+
* servers currently available, and `CAPMAX` was not specifie
|
1769
|
+
* @return LCB_EINVAL if both `persist_to` and `replicate_to` are 0.
|
1770
|
+
*/
|
1771
|
+
LIBCOUCHBASE_API
|
1772
|
+
lcb_error_t
|
1773
|
+
lcb_durability_validate(lcb_t instance,
|
1774
|
+
lcb_U16 *persist_to, lcb_U16 *replicate_to, int options);
|
1775
|
+
/**@} (NAME) */
|
1776
|
+
|
1777
|
+
|
1778
|
+
/**
|
1779
|
+
* @name Retrieve current persistence/replication status
|
1780
|
+
* @{
|
1781
|
+
*/
|
1782
|
+
|
1783
|
+
/**Set this bit in the cmdflags field to indicate that only the master node
|
1784
|
+
* should be contacted*/
|
1785
|
+
#define LCB_CMDOBSERVE_F_MASTER_ONLY (1 << 16)
|
1786
|
+
|
1787
|
+
/**@brief Structure for an observe request.
|
1788
|
+
* To request the status from _only_ the master node of the key, set the
|
1789
|
+
* LCB_CMDOBSERVE_F_MASTERONLY bit inside the lcb_CMDOBSERVE::cmdflags field
|
1790
|
+
*/
|
1791
|
+
typedef struct {
|
1792
|
+
LCB_CMD_BASE;
|
1793
|
+
/**For internal use: This determines the servers the command should be
|
1794
|
+
* routed to. Each entry is an index within the server. */
|
1795
|
+
const lcb_U16* servers_;
|
1796
|
+
size_t nservers_;
|
1797
|
+
} lcb_CMDOBSERVE;
|
1798
|
+
|
1799
|
+
/**
|
1800
|
+
* @brief Possible statuses for keys in OBSERVE response
|
1801
|
+
*/
|
1802
|
+
typedef enum {
|
1803
|
+
/** The item found in the memory, but not yet on the disk */
|
1804
|
+
LCB_OBSERVE_FOUND = 0x00,
|
1805
|
+
/** The item hit the disk */
|
1806
|
+
LCB_OBSERVE_PERSISTED = 0x01,
|
1807
|
+
/** The item missing on the disk and the memory */
|
1808
|
+
LCB_OBSERVE_NOT_FOUND = 0x80,
|
1809
|
+
/** No knowledge of the key :) */
|
1810
|
+
LCB_OBSERVE_LOGICALLY_DELETED = 0x81,
|
1811
|
+
|
1812
|
+
LCB_OBSERVE_MAX = 0x82
|
1813
|
+
} lcb_observe_t;
|
1814
|
+
|
1815
|
+
/**@brief Response structure for an observe command.
|
1816
|
+
* Note that the lcb_RESPOBSERVE::cas contains the CAS of the item as it is
|
1817
|
+
* stored within that specific server. The CAS may be incorrect or stale
|
1818
|
+
* unless lcb_RESPOBSERVE::ismaster is true.
|
1819
|
+
*/
|
1820
|
+
typedef struct {
|
1821
|
+
LCB_RESP_BASE
|
1822
|
+
lcb_U8 status; /**<Bit set of flags */
|
1823
|
+
lcb_U8 ismaster; /**< Set to true if this response came from the master node */
|
1824
|
+
lcb_U32 ttp; /**<Unused. For internal requests, contains the server index */
|
1825
|
+
lcb_U32 ttr; /**<Unused */
|
1826
|
+
} lcb_RESPOBSERVE;
|
1827
|
+
|
1828
|
+
/**
|
1829
|
+
* @brief Create a new multi context for an observe operation
|
1830
|
+
* @param instance the instance
|
1831
|
+
* @return a new multi command context, or NULL on allocation failure.
|
1832
|
+
* @committed
|
1833
|
+
*
|
1834
|
+
* Note that the callback for this command will be invoked multiple times,
|
1835
|
+
* one for each node. To determine when no more callbacks will be invoked,
|
1836
|
+
* check for the LCB_RESP_F_FINAL flag inside the lcb_RESPOBSERVE::rflags
|
1837
|
+
* field.
|
1838
|
+
*
|
1839
|
+
* @code{.c}
|
1840
|
+
* void callback(lcb_t, lcb_CALLBACKTYPE, const lcb_RESPOBSERVE *resp)
|
1841
|
+
* {
|
1842
|
+
* if (resp->rflags & LCB_RESP_F_FINAL) {
|
1843
|
+
* return;
|
1844
|
+
* }
|
1845
|
+
*
|
1846
|
+
* printf("Got status for key %.*s\n", (int)resp->nkey, resp->key);
|
1847
|
+
* printf(" Node Type: %s\n", resp->ismaster ? "MASTER" : "REPLICA");
|
1848
|
+
* printf(" Status: 0x%x\n", resp->status);
|
1849
|
+
* printf(" Current CAS: 0x%"PRIx64"\n", resp->cas);
|
1850
|
+
* }
|
1851
|
+
*
|
1852
|
+
* lcb_MULTICMD_CTX *mctx = lcb_observe3_ctxnew(instance);
|
1853
|
+
* lcb_CMDOBSERVE cmd = { 0 };
|
1854
|
+
* LCB_CMD_SET_KEY(&cmd, "key", 3);
|
1855
|
+
* mctx->addcmd(mctx, (lcb_CMDBASE *)&cmd);
|
1856
|
+
* mctx->done(mctx, cookie);
|
1857
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_OBSERVE, (lcb_RESP_cb)callback);
|
1858
|
+
* @endcode
|
1859
|
+
*
|
1860
|
+
* @warning
|
1861
|
+
* Operations created by observe cannot be undone using lcb_sched_fail().
|
1862
|
+
*/
|
1863
|
+
LIBCOUCHBASE_API
|
1864
|
+
lcb_MULTICMD_CTX *
|
1865
|
+
lcb_observe3_ctxnew(lcb_t instance);
|
1866
|
+
|
1867
|
+
/**
|
1868
|
+
* @brief Command structure for lcb_observe_seqno3().
|
1869
|
+
* Note #key, #nkey, and #cas are not used in this command.
|
1870
|
+
*/
|
1871
|
+
typedef struct {
|
1872
|
+
LCB_CMD_BASE;
|
1873
|
+
/**
|
1874
|
+
* Server index to target. The server index must be valid and must also
|
1875
|
+
* be either a master or a replica for the vBucket indicated in #vbid
|
1876
|
+
*/
|
1877
|
+
lcb_U16 server_index;
|
1878
|
+
lcb_U16 vbid; /**< vBucket ID to query */
|
1879
|
+
lcb_U64 uuid; /**< UUID known to client which should be queried */
|
1880
|
+
} lcb_CMDOBSEQNO;
|
1881
|
+
|
1882
|
+
/**
|
1883
|
+
* @brief Response structure for lcb_observe_seqno3()
|
1884
|
+
*
|
1885
|
+
* Note that #key, #nkey and #cas are empty because the operand is the relevant
|
1886
|
+
* mutation token fields in @ref lcb_CMDOBSEQNO
|
1887
|
+
*/
|
1888
|
+
typedef struct {
|
1889
|
+
LCB_RESP_BASE
|
1890
|
+
lcb_U16 vbid; /**< vBucket ID (for potential mapping) */
|
1891
|
+
lcb_U16 server_index; /**< Input server index */
|
1892
|
+
lcb_U64 cur_uuid; /**< UUID for this vBucket as known to the server */
|
1893
|
+
lcb_U64 persisted_seqno; /**< Highest persisted sequence */
|
1894
|
+
lcb_U64 mem_seqno; /**< Highest known sequence */
|
1895
|
+
|
1896
|
+
/**
|
1897
|
+
* In the case where the command's uuid is not the most current, this
|
1898
|
+
* contains the last known UUID
|
1899
|
+
*/
|
1900
|
+
lcb_U64 old_uuid;
|
1901
|
+
|
1902
|
+
/**
|
1903
|
+
* If #old_uuid is nonzero, contains the highest sequence number persisted
|
1904
|
+
* in the #old_uuid snapshot.
|
1905
|
+
*/
|
1906
|
+
lcb_U64 old_seqno;
|
1907
|
+
} lcb_RESPOBSEQNO;
|
1908
|
+
|
1909
|
+
/**
|
1910
|
+
* @volatile
|
1911
|
+
* @brief Get the persistence/replication status for a given mutation token
|
1912
|
+
* @param instance the handle
|
1913
|
+
* @param cookie callback cookie
|
1914
|
+
* @param cmd the command
|
1915
|
+
*/
|
1916
|
+
LIBCOUCHBASE_API
|
1917
|
+
lcb_error_t
|
1918
|
+
lcb_observe_seqno3(lcb_t instance, const void *cookie, const lcb_CMDOBSEQNO *cmd);
|
1919
|
+
|
1920
|
+
/**@} (Name: OBSERVE) */
|
1921
|
+
/**@} (Group: Durability) */
|
1922
|
+
|
1923
|
+
/**
|
1924
|
+
* @ingroup lcb-public-api
|
1925
|
+
* @defgroup lcb-mutation-tokens Mutation Tokens
|
1926
|
+
*
|
1927
|
+
* @details Mutation Tokens are returned with mutations if
|
1928
|
+
* ::LCB_CNTL_FETCH_MUTATION_TOKENS is enabled (off by default). Mutation tokens
|
1929
|
+
* are largely of internal use, but can be used by N1QL queries and durability
|
1930
|
+
* requirement polling
|
1931
|
+
*
|
1932
|
+
* @addtogroup lcb-mutation-tokens
|
1933
|
+
* @{
|
1934
|
+
*/
|
1935
|
+
|
1936
|
+
/**
|
1937
|
+
* @brief
|
1938
|
+
* Structure representing a synchronization token. This token may be used
|
1939
|
+
* for durability operations and N1QL queries. The contents of this structure
|
1940
|
+
* should be considered opaque, and accessed via the various macros
|
1941
|
+
* @struct lcb_MUTATION_TOKEN
|
1942
|
+
*/
|
1943
|
+
|
1944
|
+
/** Get the vBucket UUID */
|
1945
|
+
#define LCB_MUTATION_TOKEN_ID(p) ((p)->uuid_)
|
1946
|
+
/** Get the sequence number */
|
1947
|
+
#define LCB_MUTATION_TOKEN_SEQ(p) ((p)->seqno_)
|
1948
|
+
/** Get the vBucket number itself */
|
1949
|
+
#define LCB_MUTATION_TOKEN_VB(p) ((p)->vbid_)
|
1950
|
+
/** Whether this mutation token has valid contents */
|
1951
|
+
#define LCB_MUTATION_TOKEN_ISVALID(p) \
|
1952
|
+
(p && !((p)->uuid_ == 0 && (p)->seqno_ == 0 && (p)->vbid_ == 0))
|
1953
|
+
|
1954
|
+
/**
|
1955
|
+
* Retrieves the mutation token from the response structure
|
1956
|
+
* @param cbtype the type of callback invoked
|
1957
|
+
* @param rb the pointer to the response
|
1958
|
+
* @return The embedded mutation token, or NULL if the response does not have a
|
1959
|
+
* mutation token. This may be either because the command does not support
|
1960
|
+
* mutation tokens, or because they have been disabled at the connection
|
1961
|
+
* level.
|
1962
|
+
*/
|
1963
|
+
LIBCOUCHBASE_API
|
1964
|
+
const lcb_MUTATION_TOKEN *
|
1965
|
+
lcb_resp_get_mutation_token(int cbtype, const lcb_RESPBASE *rb);
|
1966
|
+
|
1967
|
+
/**
|
1968
|
+
* @volatile
|
1969
|
+
*
|
1970
|
+
* Retrieves the last mutation token for a given key.
|
1971
|
+
* This relies on the @ref LCB_CNTL_DURABILITY_MUTATION_TOKENS option, and will
|
1972
|
+
* check the instance-level log to determine the latest MUTATION_TOKEN for
|
1973
|
+
* the given vBucket ID which the key maps to.
|
1974
|
+
*
|
1975
|
+
* @param instance the instance
|
1976
|
+
* @param kb The buffer representing the key. The type of the buffer (see
|
1977
|
+
* lcb_KEYBUF::type) may either be ::LCB_KV_COPY or ::LCB_KV_VBID
|
1978
|
+
* @param[out] errp Set to an error if this function returns NULL
|
1979
|
+
* @return The mutation token if successful, otherwise NULL.
|
1980
|
+
*
|
1981
|
+
* Getting the latest mutation token for a key:
|
1982
|
+
*
|
1983
|
+
* @code{.c}
|
1984
|
+
* lcb_KEYBUF kb;
|
1985
|
+
* kb.type = LCB_KV_COPY;
|
1986
|
+
* kb.contig.bytes = "Hello";
|
1987
|
+
* kv.config.nbytes = 5;
|
1988
|
+
* mt = lcb_get_mutation_token(instance, &kb, &rc);
|
1989
|
+
* @endcode
|
1990
|
+
*
|
1991
|
+
* Getting the latest mutation token for a vbucket:
|
1992
|
+
* @code{.c}
|
1993
|
+
* lcb_KEYBUF kb;
|
1994
|
+
* kv.type = LCB_KV_VBID;
|
1995
|
+
* kv.contig.nbytes = 543;
|
1996
|
+
* kv.config.bytes = NULL;
|
1997
|
+
* mt = lcb_get_mutation_token(instance, &kb, &rc);
|
1998
|
+
* @endcode
|
1999
|
+
*
|
2000
|
+
* Getting the mutation token for each vbucket
|
2001
|
+
* @code{.c}
|
2002
|
+
* size_t ii, nvb;
|
2003
|
+
* lcbvb_CONFIG *vbc;
|
2004
|
+
* lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_VBCONFIG, &vbc);
|
2005
|
+
* nvb = vbucket_get_num_vbuckets(vbc);
|
2006
|
+
* for (ii = 0; ii < nvb; ii++) {
|
2007
|
+
* lcb_KEYBUF kb;
|
2008
|
+
* const lcb_MUTATION_TOKEN *mt;
|
2009
|
+
* kb.type = LCB_KV_VBID;
|
2010
|
+
* kb.contig.nbytes = ii;
|
2011
|
+
* kb.config.bytes = NULL;
|
2012
|
+
* mt = lcb_get_mutation_token(instance, &kb, &rc);
|
2013
|
+
* }
|
2014
|
+
* @endcode
|
2015
|
+
*/
|
2016
|
+
LIBCOUCHBASE_API
|
2017
|
+
const lcb_MUTATION_TOKEN *
|
2018
|
+
lcb_get_mutation_token(lcb_t instance, const lcb_KEYBUF *kb, lcb_error_t *errp);
|
2019
|
+
|
2020
|
+
/**@} (Group: Mutation Tokens) */
|
2021
|
+
|
2022
|
+
/**
|
2023
|
+
* @ingroup lcb-kv-api
|
2024
|
+
* @defgroup lcb-counter Counters
|
2025
|
+
* @brief Manipulate the numeric content of a document
|
2026
|
+
* @details Counter operations treat the document being accessed as a numeric
|
2027
|
+
* value (the document should contain a parseable integer as its content). This
|
2028
|
+
* value may then be incremented or decremented.
|
2029
|
+
*
|
2030
|
+
* @addtogroup lcb-counter
|
2031
|
+
* @{
|
2032
|
+
*/
|
2033
|
+
|
2034
|
+
/**
|
2035
|
+
* @brief Command for counter operations.
|
2036
|
+
* @see lcb_counter3(), lcb_RESPCOUNTER.
|
2037
|
+
*
|
2038
|
+
* @warning You may only set the #exptime member if the #create member is set
|
2039
|
+
* to a true value. Setting `exptime` otherwise will cause the operation to
|
2040
|
+
* fail with @ref LCB_OPTIONS_CONFLICT
|
2041
|
+
*
|
2042
|
+
* @warning The #cas member should be set to 0 for this operation. As this
|
2043
|
+
* operation itself is atomic, specifying a CAS is not necessary.
|
2044
|
+
*/
|
2045
|
+
typedef struct {
|
2046
|
+
LCB_CMD_BASE;
|
2047
|
+
/**Delta value. If this number is negative the item on the server is
|
2048
|
+
* decremented. If this number is positive then the item on the server
|
2049
|
+
* is incremented */
|
2050
|
+
lcb_int64_t delta;
|
2051
|
+
/**If the item does not exist on the server (and `create` is true) then
|
2052
|
+
* this will be the initial value for the item. */
|
2053
|
+
lcb_U64 initial;
|
2054
|
+
/**Boolean value. Create the item and set it to `initial` if it does not
|
2055
|
+
* already exist */
|
2056
|
+
int create;
|
2057
|
+
} lcb_CMDCOUNTER;
|
2058
|
+
|
2059
|
+
/**
|
2060
|
+
* @brief Response structure for counter operations
|
2061
|
+
* @see lcb_counter3()
|
2062
|
+
*/
|
2063
|
+
typedef struct {
|
2064
|
+
LCB_RESP_BASE
|
2065
|
+
/** Contains the _current_ value after the operation was performed */
|
2066
|
+
lcb_U64 value;
|
2067
|
+
} lcb_RESPCOUNTER;
|
2068
|
+
|
2069
|
+
/**@committed
|
2070
|
+
* @brief Schedule single counter operation
|
2071
|
+
* @param instance the instance
|
2072
|
+
* @param cookie the pointer to associate with the request
|
2073
|
+
* @param cmd the command to use
|
2074
|
+
* @return LCB_SUCCESS on success, other error on failure
|
2075
|
+
*
|
2076
|
+
* @par Request
|
2077
|
+
* @code{.c}
|
2078
|
+
* lcb_CMDCOUNTER cmd = { 0 };
|
2079
|
+
* LCB_CMD_SET_KEY(&cmd, "counter", strlen("counter"));
|
2080
|
+
* cmd.delta = 1; // Increment by one
|
2081
|
+
* cmd.initial = 42; // Default value is 42 if it does not exist
|
2082
|
+
* cmd.exptime = 300; // Expire in 5 minutes
|
2083
|
+
* lcb_counter3(instance, NULL, &cmd);
|
2084
|
+
* lcb_wait3(instance, LCB_WAIT_NOCHECK);
|
2085
|
+
* @endcode
|
2086
|
+
*
|
2087
|
+
* @par Response
|
2088
|
+
* @code{.c}
|
2089
|
+
* lcb_install_callback3(instance, LCB_CALLBACKTYPE_COUNTER, counter_cb);
|
2090
|
+
* void counter_cb(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
|
2091
|
+
* {
|
2092
|
+
* const lcb_RESPCOUNTER *resp = (const lcb_RESPCOUNTER *)rb;
|
2093
|
+
* if (resp->rc == LCB_SUCCESS) {
|
2094
|
+
* printf("Incremented counter for %.*s. Current value %llu\n",
|
2095
|
+
* (int)resp->nkey, resp->key, resp->value);
|
2096
|
+
* }
|
2097
|
+
* }
|
2098
|
+
* @endcode
|
2099
|
+
*
|
2100
|
+
* @par Callback Errors
|
2101
|
+
* In addition to generic errors, the following errors may be returned in the
|
2102
|
+
* callback (via lcb_RESPBASE::rc):
|
2103
|
+
*
|
2104
|
+
* @cb_err ::LCB_KEY_ENOENT if the counter doesn't exist
|
2105
|
+
* (and lcb_CMDCOUNTER::create was not set)
|
2106
|
+
* @cb_err ::LCB_DELTA_BADVAL if the existing document's content could not
|
2107
|
+
* be parsed as a number by the server.
|
2108
|
+
*/
|
2109
|
+
LIBCOUCHBASE_API
|
2110
|
+
lcb_error_t
|
2111
|
+
lcb_counter3(lcb_t instance, const void *cookie, const lcb_CMDCOUNTER *cmd);
|
2112
|
+
/**@} (Group: Counter) */
|
2113
|
+
|
2114
|
+
/**@ingroup lcb-kv-api
|
2115
|
+
* @defgroup lcb-lock Lock/Unlock
|
2116
|
+
* @details Documents may be locked and unlocked on the server. While a document
|
2117
|
+
* is locked, any attempt to modify it (or lock it again) will fail.
|
2118
|
+
*
|
2119
|
+
* @note Locks are not persistent across nodes (if a node fails over, the lock
|
2120
|
+
* is not transferred to a replica).
|
2121
|
+
* @note The recommended way to manage access and concurrency control for
|
2122
|
+
* documents in Couchbase is through the CAS (See lcb_CMDBASE::cas and
|
2123
|
+
* lcb_RESPBASE::cas), which can also be considered a form of opportunistic
|
2124
|
+
* locking.
|
2125
|
+
*
|
2126
|
+
* @par Locking an item
|
2127
|
+
* There is no exclusive function to lock an item. Locking an item is done
|
2128
|
+
* using @ref lcb_get3(), by setting the lcb_CMDGET::lock option to true.
|
2129
|
+
*
|
2130
|
+
* @addtogroup lcb-lock
|
2131
|
+
* @{
|
2132
|
+
*/
|
2133
|
+
|
2134
|
+
/**@brief Command for lcb_unlock3()
|
2135
|
+
* @attention lcb_CMDBASE::cas must be specified, or the operation will fail on
|
2136
|
+
* the server*/
|
2137
|
+
typedef lcb_CMDBASE lcb_CMDUNLOCK;
|
2138
|
+
|
2139
|
+
/**@brief Response structure for an unlock command.
|
2140
|
+
* @note the lcb_RESPBASE::cas field does not contain the CAS of the item*/
|
2141
|
+
typedef lcb_RESPBASE lcb_RESPUNLOCK;
|
2142
|
+
|
2143
|
+
/**
|
2144
|
+
* @committed
|
2145
|
+
* @brief
|
2146
|
+
* Unlock a previously locked item using lcb_CMDGET::lock
|
2147
|
+
*
|
2148
|
+
* @param instance the instance
|
2149
|
+
* @param cookie the context pointer to associate with the command
|
2150
|
+
* @param cmd the command containing the information about the locked key
|
2151
|
+
* @return LCB_SUCCESS if successful, an error code otherwise
|
2152
|
+
* @see lcb_get3()
|
2153
|
+
*
|
2154
|
+
* @par Request
|
2155
|
+
*
|
2156
|
+
* @code{.c}
|
2157
|
+
* void locked_callback(lcb_t, lcb_CALLBACKTYPE, const lcb_RESPBASE *resp) {
|
2158
|
+
* lcb_CMDUNLOCK cmd = { 0 };
|
2159
|
+
* LCB_CMD_SET_KEY(&cmd, resp->key, resp->nkey);
|
2160
|
+
* cmd.cas = resp->cas;
|
2161
|
+
* lcb_unlock3(instance, cookie, &cmd);
|
2162
|
+
* }
|
2163
|
+
*
|
2164
|
+
* @endcode
|
2165
|
+
*/
|
2166
|
+
LIBCOUCHBASE_API
|
2167
|
+
lcb_error_t
|
2168
|
+
lcb_unlock3(lcb_t instance, const void *cookie, const lcb_CMDUNLOCK *cmd);
|
2169
|
+
/**@} (Group: Unlock) */
|
2170
|
+
|
2171
|
+
/**@ingroup lcb-kv-api
|
2172
|
+
* @defgroup lcb-touch Touch/Expiry
|
2173
|
+
* @brief Modify or clear a document's expiration time
|
2174
|
+
* @details Couchbase allows documents to contain expiration times
|
2175
|
+
* (see lcb_CMDBASE::exptime). Most operations allow the expiry time to be
|
2176
|
+
* updated, however lcb_touch3() allows the exclusive update of the expiration
|
2177
|
+
* time without additional network overhead.
|
2178
|
+
*
|
2179
|
+
* @addtogroup lcb-touch
|
2180
|
+
* @{
|
2181
|
+
*/
|
2182
|
+
|
2183
|
+
/**
|
2184
|
+
* @brief Command structure for a touch request
|
2185
|
+
* @note The lcb_CMDTOUCH::cas field is ignored. The item's modification time
|
2186
|
+
* is always updated regardless if the CAS on the server differs.
|
2187
|
+
* The #exptime field is always used. If 0 then the expiry on the server is
|
2188
|
+
* cleared.
|
2189
|
+
*/
|
2190
|
+
typedef lcb_CMDBASE lcb_CMDTOUCH;
|
2191
|
+
|
2192
|
+
/**@brief Response structure for a touch request
|
2193
|
+
* @note the lcb_RESPTOUCH::cas field contains the current CAS of the item*/
|
2194
|
+
typedef lcb_RESPBASE lcb_RESPTOUCH;
|
2195
|
+
|
2196
|
+
/**@committed
|
2197
|
+
* @brief Spool a touch request
|
2198
|
+
* @param instance the handle
|
2199
|
+
* @param cookie the pointer to associate with the request
|
2200
|
+
* @param cmd the command
|
2201
|
+
* @return LCB_SUCCESS on success, other error code on failure
|
2202
|
+
*
|
2203
|
+
* @par Request
|
2204
|
+
* @code{.c}
|
2205
|
+
* lcb_CMDTOUCH cmd = { 0 };
|
2206
|
+
* LCB_CMD_SET_KEY(&cmd, "keep_me", strlen("keep_me"));
|
2207
|
+
* cmd.exptime = 0; // Clear the expiration
|
2208
|
+
* lcb_touch3(instance, cookie, &cmd);
|
2209
|
+
* @endcode
|
2210
|
+
*
|
2211
|
+
* @par Response
|
2212
|
+
* @code{.c}
|
2213
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_TOUCH, touch_callback);
|
2214
|
+
* void touch_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
|
2215
|
+
* {
|
2216
|
+
* if (rb->rc == LCB_SUCCESS) {
|
2217
|
+
* printf("Touch succeeded\n");
|
2218
|
+
* }
|
2219
|
+
* }
|
2220
|
+
* @endcode
|
2221
|
+
*/
|
2222
|
+
LIBCOUCHBASE_API
|
2223
|
+
lcb_error_t
|
2224
|
+
lcb_touch3(lcb_t instance, const void *cookie, const lcb_CMDTOUCH *cmd);
|
2225
|
+
/**@} (Group: Touch) */
|
2226
|
+
/**@} (Group: KV API) */
|
2227
|
+
|
2228
|
+
/**@ingroup lcb-public-api
|
2229
|
+
* @defgroup lcb-misc-cmds Miscellaneous Commands
|
2230
|
+
* @brief Additional miscellaneous commands which can be executed on the server.
|
2231
|
+
*
|
2232
|
+
* @addtogroup lcb-misc-cmds
|
2233
|
+
* @{
|
2234
|
+
*/
|
2235
|
+
|
2236
|
+
/**
|
2237
|
+
* @name Server Statistics
|
2238
|
+
* @{
|
2239
|
+
*/
|
2240
|
+
|
2241
|
+
/**
|
2242
|
+
* @brief Command structure for stats request
|
2243
|
+
* The lcb_CMDSTATS::key field should contain the statistics key, or be empty
|
2244
|
+
* if the default statistics are desired.
|
2245
|
+
* The #cmdflags field may contain the @ref LCB_CMDSTATS_F_KV flag.
|
2246
|
+
*/
|
2247
|
+
typedef lcb_CMDBASE lcb_CMDSTATS;
|
2248
|
+
|
2249
|
+
/**
|
2250
|
+
* The key is a stored item for which statistics should be retrieved. This
|
2251
|
+
* invokes the 'keystats' semantics. Note that when using _keystats_, a key
|
2252
|
+
* must be present, and must not have any spaces in it.
|
2253
|
+
*/
|
2254
|
+
#define LCB_CMDSTATS_F_KV (1 << 16)
|
2255
|
+
|
2256
|
+
/**@brief Response structure for cluster statistics.
|
2257
|
+
* The lcb_RESPSTATS::key field contains the statistic name (_not_ the same
|
2258
|
+
* as was passed in lcb_CMDSTATS::key which is the name of the statistical
|
2259
|
+
* _group_).*/
|
2260
|
+
typedef struct {
|
2261
|
+
LCB_RESP_BASE
|
2262
|
+
LCB_RESP_SERVER_FIELDS
|
2263
|
+
const char *value; /**< The value, if any, for the given statistic */
|
2264
|
+
lcb_SIZE nvalue; /**< Length of value */
|
2265
|
+
} lcb_RESPSTATS;
|
2266
|
+
|
2267
|
+
/**@committed
|
2268
|
+
* @brief Schedule a request for statistics from the cluster.
|
2269
|
+
* @param instance the instance
|
2270
|
+
* @param cookie pointer to associate with the request
|
2271
|
+
* @param cmd the command
|
2272
|
+
* @return LCB_SUCCESS on success, other error code on failure.
|
2273
|
+
*
|
2274
|
+
* Note that the callback for this command is invoked an indeterminate amount
|
2275
|
+
* of times. The callback is invoked once for each statistic for each server.
|
2276
|
+
* When all the servers have responded with their statistics, a final callback
|
2277
|
+
* is delivered to the application with the LCB_RESP_F_FINAL flag set in the
|
2278
|
+
* lcb_RESPSTATS::rflags field. When this response is received no more callbacks
|
2279
|
+
* for this command shall be invoked.
|
2280
|
+
*
|
2281
|
+
* @par Request
|
2282
|
+
* @code{.c}
|
2283
|
+
* lcb_CMDSTATS cmd = { 0 };
|
2284
|
+
* // Using default stats, no further initialization
|
2285
|
+
* lcb_stats3(instance, fp, &cmd);
|
2286
|
+
* lcb_wait(instance);
|
2287
|
+
* @endcode
|
2288
|
+
*
|
2289
|
+
* @par Response
|
2290
|
+
* @code{.c}
|
2291
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_STATS, stats_callback);
|
2292
|
+
* void stats_callback(lcb_t, int, const lcb_RESPBASE *rb)
|
2293
|
+
* {
|
2294
|
+
* const lcb_RESPSTATS *resp = (const lcb_RESPSTATS*)rb;
|
2295
|
+
* if (resp->key) {
|
2296
|
+
* printf("Server %s: %.*s = %.*s\n", resp->server,
|
2297
|
+
* (int)resp->nkey, resp->key,
|
2298
|
+
* (int)resp->nvalue, resp->value);
|
2299
|
+
* }
|
2300
|
+
* if (resp->rflags & LCB_RESP_F_FINAL) {
|
2301
|
+
* printf("No more replies remaining!\n");
|
2302
|
+
* }
|
2303
|
+
* }
|
2304
|
+
* @endcode
|
2305
|
+
*/
|
2306
|
+
LIBCOUCHBASE_API
|
2307
|
+
lcb_error_t
|
2308
|
+
lcb_stats3(lcb_t instance, const void *cookie, const lcb_CMDSTATS * cmd);
|
2309
|
+
/**@} (Name: Stats) */
|
2310
|
+
|
2311
|
+
/**@name Server Versions
|
2312
|
+
* @warning This does not return the actual _Couchbase_ version but rather
|
2313
|
+
* the internal version of the memcached server.
|
2314
|
+
* @{
|
2315
|
+
*/
|
2316
|
+
|
2317
|
+
/**@brief Response structure for the version command */
|
2318
|
+
typedef struct {
|
2319
|
+
LCB_RESP_BASE
|
2320
|
+
LCB_RESP_SERVER_FIELDS
|
2321
|
+
const char *mcversion; /**< The version string */
|
2322
|
+
lcb_SIZE nversion; /**< Length of the version string */
|
2323
|
+
} lcb_RESPMCVERSION;
|
2324
|
+
|
2325
|
+
/**
|
2326
|
+
* @volatile
|
2327
|
+
*/
|
2328
|
+
LIBCOUCHBASE_API
|
2329
|
+
lcb_error_t
|
2330
|
+
lcb_server_versions3(lcb_t instance, const void *cookie, const lcb_CMDBASE * cmd);
|
2331
|
+
|
2332
|
+
/**@} (Name: MCversion) */
|
2333
|
+
|
2334
|
+
/**
|
2335
|
+
* @name Server Log Verbosity
|
2336
|
+
* @{
|
2337
|
+
*/
|
2338
|
+
|
2339
|
+
/** @brief `level` field for lcb_server_verbosity3 () */
|
2340
|
+
typedef enum {
|
2341
|
+
LCB_VERBOSITY_DETAIL = 0x00,
|
2342
|
+
LCB_VERBOSITY_DEBUG = 0x01,
|
2343
|
+
LCB_VERBOSITY_INFO = 0x02,
|
2344
|
+
LCB_VERBOSITY_WARNING = 0x03
|
2345
|
+
} lcb_verbosity_level_t;
|
2346
|
+
|
2347
|
+
typedef struct {
|
2348
|
+
/* unused */
|
2349
|
+
LCB_CMD_BASE;
|
2350
|
+
const char *server;
|
2351
|
+
lcb_verbosity_level_t level;
|
2352
|
+
} lcb_CMDVERBOSITY;
|
2353
|
+
typedef lcb_RESPSERVERBASE lcb_RESPVERBOSITY;
|
2354
|
+
/**@volatile*/
|
2355
|
+
LIBCOUCHBASE_API
|
2356
|
+
lcb_error_t
|
2357
|
+
lcb_server_verbosity3(lcb_t instance, const void *cookie, const lcb_CMDVERBOSITY *cmd);
|
2358
|
+
/**@} (Name: Verbosity) */
|
2359
|
+
/**@} (Group: Misc) */
|
2360
|
+
|
2361
|
+
/**
|
2362
|
+
* @ingroup lcb-public-api
|
2363
|
+
* @defgroup lcb-flush Flush
|
2364
|
+
* @brief Clear the contents of a bucket
|
2365
|
+
*
|
2366
|
+
* Flush is useful for development environments (for example clearing a bucket
|
2367
|
+
* before running tests).
|
2368
|
+
*
|
2369
|
+
* @addtogroup lcb-flush
|
2370
|
+
* @{
|
2371
|
+
*/
|
2372
|
+
typedef lcb_CMDBASE lcb_CMDCBFLUSH;
|
2373
|
+
typedef lcb_RESPBASE lcb_RESPCBFLUSH;
|
2374
|
+
|
2375
|
+
/**
|
2376
|
+
* @uncommitted
|
2377
|
+
*
|
2378
|
+
* Flush a bucket
|
2379
|
+
* This function will properly flush any type of bucket using the REST API
|
2380
|
+
* via HTTP. This may be used in a manner similar to the older lcb_flush3().
|
2381
|
+
*
|
2382
|
+
* The callback invoked under ::LCB_CALLBACK_CBFLUSH will be invoked with either
|
2383
|
+
* a success or failure status depending on the outcome of the operation. Note
|
2384
|
+
* that in order for lcb_cbflush3() to succeed, flush must already be enabled
|
2385
|
+
* on the bucket via the administrative interface.
|
2386
|
+
*
|
2387
|
+
* @param instance the library handle
|
2388
|
+
* @param cookie the cookie passed in the callback
|
2389
|
+
* @param cmd empty command structure. Currently there are no options for this
|
2390
|
+
* command.
|
2391
|
+
* @return status code for scheduling.
|
2392
|
+
*
|
2393
|
+
* @attention
|
2394
|
+
* Because this command is built using HTTP, this is not subject to operation
|
2395
|
+
* pipeline calls such as lcb_sched_enter()/lcb_sched_leave()
|
2396
|
+
*/
|
2397
|
+
LIBCOUCHBASE_API
|
2398
|
+
lcb_error_t
|
2399
|
+
lcb_cbflush3(lcb_t instance, const void *cookie, const lcb_CMDCBFLUSH *cmd);
|
2400
|
+
|
2401
|
+
|
2402
|
+
typedef lcb_CMDBASE lcb_CMDFLUSH;
|
2403
|
+
typedef lcb_RESPSERVERBASE lcb_RESPFLUSH;
|
2404
|
+
/**
|
2405
|
+
* @volatile
|
2406
|
+
* @deprecated
|
2407
|
+
*/
|
2408
|
+
LIBCOUCHBASE_API
|
2409
|
+
lcb_error_t
|
2410
|
+
lcb_flush3(lcb_t instance, const void *cookie, const lcb_CMDFLUSH *cmd);
|
2411
|
+
/**@} (Group: Flush) */
|
2412
|
+
|
2413
|
+
/**
|
2414
|
+
* @ingroup lcb-public-api
|
2415
|
+
* @defgroup lcb-noop NOOP
|
2416
|
+
* @brief Send NOOP command to server
|
2417
|
+
*
|
2418
|
+
* @addtogroup lcb-noop
|
2419
|
+
* @{
|
2420
|
+
*/
|
2421
|
+
typedef lcb_CMDBASE lcb_CMDNOOP;
|
2422
|
+
typedef lcb_RESPSERVERBASE lcb_RESPNOOP;
|
2423
|
+
|
2424
|
+
/**
|
2425
|
+
* @committed
|
2426
|
+
*
|
2427
|
+
* Send NOOP to the node
|
2428
|
+
*
|
2429
|
+
* @param instance the library handle
|
2430
|
+
* @param cookie the cookie passed in the callback
|
2431
|
+
* @param cmd empty command structure.
|
2432
|
+
* @return status code for scheduling.
|
2433
|
+
*/
|
2434
|
+
LIBCOUCHBASE_API
|
2435
|
+
lcb_error_t
|
2436
|
+
lcb_noop3(lcb_t instance, const void *cookie, const lcb_CMDNOOP *cmd);
|
2437
|
+
/**@} (Group: NOOP) */
|
2438
|
+
|
2439
|
+
/**
|
2440
|
+
* @ingroup lcb-public-api
|
2441
|
+
* @defgroup lcb-ping PING
|
2442
|
+
* @brief Broadcast NOOP-like commands to each service in the cluster
|
2443
|
+
*
|
2444
|
+
* @addtogroup lcb-ping
|
2445
|
+
* @{
|
2446
|
+
*/
|
2447
|
+
|
2448
|
+
/**
|
2449
|
+
* Ping data (Key/Value) service. Used in lcb_CMDPING#services
|
2450
|
+
*/
|
2451
|
+
#define LCB_PINGSVC_F_KV 0x01
|
2452
|
+
|
2453
|
+
/**
|
2454
|
+
* Ping query (N1QL) service. Used in lcb_CMDPING#services
|
2455
|
+
*/
|
2456
|
+
#define LCB_PINGSVC_F_N1QL 0x02
|
2457
|
+
|
2458
|
+
/**
|
2459
|
+
* Ping views (Map/Reduce) service. Used in lcb_CMDPING#services
|
2460
|
+
*/
|
2461
|
+
#define LCB_PINGSVC_F_VIEWS 0x04
|
2462
|
+
|
2463
|
+
/**
|
2464
|
+
* Ping full text search (FTS) service. Used in lcb_CMDPING#services
|
2465
|
+
*/
|
2466
|
+
#define LCB_PINGSVC_F_FTS 0x08
|
2467
|
+
|
2468
|
+
/**
|
2469
|
+
* Ping Analytics for N1QL service. Used in lcb_CMDPING#services
|
2470
|
+
*/
|
2471
|
+
#define LCB_PINGSVC_F_ANALYTICS 0x10
|
2472
|
+
|
2473
|
+
/**
|
2474
|
+
* Do not record any metrics or status codes from ping responses.
|
2475
|
+
* This might be useful to reduce overhead, when user-space
|
2476
|
+
* keep-alive mechanism is not interested in actual latencies,
|
2477
|
+
* but rather need keep sockets active. Used in lcb_CMDPING#options
|
2478
|
+
*/
|
2479
|
+
#define LCB_PINGOPT_F_NOMETRICS 0x01
|
2480
|
+
|
2481
|
+
/**
|
2482
|
+
* Automatically encode PING result as JSON. See njson/json fields
|
2483
|
+
* of #lcb_RESPPING structure. Used in lcb_CMDPING#options
|
2484
|
+
*/
|
2485
|
+
#define LCB_PINGOPT_F_JSON 0x02
|
2486
|
+
|
2487
|
+
/**
|
2488
|
+
* Add extra details about service status into generated JSON.
|
2489
|
+
* Requires LCB_PINGOPT_F_JSON to be set. Used in lcb_CMDPING#options
|
2490
|
+
*/
|
2491
|
+
#define LCB_PINGOPT_F_JSONDETAILS 0x04
|
2492
|
+
|
2493
|
+
/**
|
2494
|
+
* Generate indented JSON, which is better for reading. Used in lcb_CMDPING#options
|
2495
|
+
*/
|
2496
|
+
#define LCB_PINGOPT_F_JSONPRETTY 0x08
|
2497
|
+
|
2498
|
+
/**
|
2499
|
+
* Structure for PING requests.
|
2500
|
+
*
|
2501
|
+
* @committed
|
2502
|
+
*/
|
2503
|
+
typedef struct {
|
2504
|
+
LCB_CMD_BASE;
|
2505
|
+
int services; /**< bitmap for services to ping */
|
2506
|
+
int options; /**< extra options, e.g. for result representation */
|
2507
|
+
const char *id; /**< optional, zero-terminated string to identify the report */
|
2508
|
+
} lcb_CMDPING;
|
2509
|
+
|
2510
|
+
/**
|
2511
|
+
* Type of the service. This enumeration is used in PING responses.
|
2512
|
+
*
|
2513
|
+
* @committed
|
2514
|
+
*/
|
2515
|
+
typedef enum {
|
2516
|
+
LCB_PINGSVC_KV = 0,
|
2517
|
+
LCB_PINGSVC_VIEWS,
|
2518
|
+
LCB_PINGSVC_N1QL,
|
2519
|
+
LCB_PINGSVC_FTS,
|
2520
|
+
LCB_PINGSVC__MAX
|
2521
|
+
} lcb_PINGSVCTYPE;
|
2522
|
+
|
2523
|
+
/**
|
2524
|
+
* Status of the service
|
2525
|
+
*
|
2526
|
+
* @committed
|
2527
|
+
*/
|
2528
|
+
typedef enum {
|
2529
|
+
LCB_PINGSTATUS_OK = 0,
|
2530
|
+
LCB_PINGSTATUS_TIMEOUT,
|
2531
|
+
LCB_PINGSTATUS_ERROR,
|
2532
|
+
LCB_PINGSTATUS__MAX
|
2533
|
+
} lcb_PINGSTATUS;
|
2534
|
+
|
2535
|
+
/**
|
2536
|
+
* Entry describing the status of the service in the cluster.
|
2537
|
+
* It is part of lcb_RESPING structure.
|
2538
|
+
*
|
2539
|
+
* @committed
|
2540
|
+
*/
|
2541
|
+
typedef struct {
|
2542
|
+
lcb_PINGSVCTYPE type; /**< type of the service */
|
2543
|
+
/* TODO: rename to "remote" */
|
2544
|
+
const char *server; /**< server host:port */
|
2545
|
+
lcb_U64 latency; /**< latency in nanoseconds */
|
2546
|
+
lcb_error_t rc; /**< raw return code of the operation */
|
2547
|
+
const char *local; /**< server host:port */
|
2548
|
+
const char *id; /**< service identifier (unique in scope of lcb_t connection instance) */
|
2549
|
+
const char *scope; /**< optional scope name (typically equals to the bucket name) */
|
2550
|
+
lcb_PINGSTATUS status; /**< status of the operation */
|
2551
|
+
} lcb_PINGSVC;
|
2552
|
+
|
2553
|
+
/**
|
2554
|
+
* Structure for PING responses.
|
2555
|
+
*
|
2556
|
+
* @committed
|
2557
|
+
*/
|
2558
|
+
typedef struct {
|
2559
|
+
LCB_RESP_BASE
|
2560
|
+
LCB_RESP_SERVER_FIELDS
|
2561
|
+
lcb_SIZE nservices; /**< number of the nodes, replied to ping */
|
2562
|
+
lcb_PINGSVC *services; /**< the nodes, replied to ping, if any */
|
2563
|
+
lcb_SIZE njson; /**< length of JSON string (when #LCB_PINGOPT_F_JSON was specified) */
|
2564
|
+
const char *json; /**< pointer to JSON string */
|
2565
|
+
} lcb_RESPPING;
|
2566
|
+
|
2567
|
+
/**
|
2568
|
+
* @brief Check connections by sending NOOP-like messages to all services.
|
2569
|
+
*
|
2570
|
+
* @committed
|
2571
|
+
*
|
2572
|
+
* When no metrics, required, it is possible to reduce memory overhead
|
2573
|
+
* by turning off response contents using #LCB_PINGOPT_F_NOMETRICS.
|
2574
|
+
*
|
2575
|
+
* @par Request
|
2576
|
+
* @code{.c}
|
2577
|
+
* lcb_CMDPING cmd = { 0 };
|
2578
|
+
* // select services to ping
|
2579
|
+
* cmd.services = LCB_PINGSVC_F_KV | LCB_PINGSVC_F_N1QL;
|
2580
|
+
* lcb_ping3(instance, fp, &cmd);
|
2581
|
+
* lcb_wait(instance);
|
2582
|
+
* @endcode
|
2583
|
+
*
|
2584
|
+
* @par Response
|
2585
|
+
* @code{.c}
|
2586
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_PING, ping_callback);
|
2587
|
+
* void ping_callback(lcb_t, int, const lcb_RESPBASE *rb)
|
2588
|
+
* {
|
2589
|
+
* const lcb_RESPPING *resp = (const lcb_RESPPING*)rb;
|
2590
|
+
* int ii;
|
2591
|
+
* for (ii = 0; ii < resp->nservices; ii++) {
|
2592
|
+
* printf("service: %s, status: %d, host: %s, latency: %lu nanoseconds\n",
|
2593
|
+
* resp->services[ii].type == LCB_PINGSVC_KV ? "KV" : "N1QL",
|
2594
|
+
* resp->services[ii].status,
|
2595
|
+
* resp->services[ii].server,
|
2596
|
+
* (unsigned long)resp->services[ii].latency);
|
2597
|
+
* }
|
2598
|
+
* }
|
2599
|
+
* @endcode
|
2600
|
+
* @param instance the library handle
|
2601
|
+
* @param cookie the cookie passed in the callback
|
2602
|
+
* @param cmd empty command structure.
|
2603
|
+
* @return status code for scheduling.
|
2604
|
+
*/
|
2605
|
+
LIBCOUCHBASE_API
|
2606
|
+
lcb_error_t
|
2607
|
+
lcb_ping3(lcb_t instance, const void *cookie, const lcb_CMDPING *cmd);
|
2608
|
+
|
2609
|
+
typedef struct {
|
2610
|
+
LCB_CMD_BASE;
|
2611
|
+
int options; /**< extra options, e.g. for result representation */
|
2612
|
+
const char *id; /**< optional, zero-terminated string to identify the report */
|
2613
|
+
} lcb_CMDDIAG;
|
2614
|
+
|
2615
|
+
typedef struct {
|
2616
|
+
LCB_RESP_BASE
|
2617
|
+
lcb_SIZE njson; /**< length of JSON string (when #LCB_PINGOPT_F_JSON was specified) */
|
2618
|
+
const char *json; /**< pointer to JSON string */
|
2619
|
+
} lcb_RESPDIAG;
|
2620
|
+
|
2621
|
+
/**
|
2622
|
+
* @brief Returns diagnostics report about network connections.
|
2623
|
+
*
|
2624
|
+
* @committed
|
2625
|
+
*
|
2626
|
+
* @par Request
|
2627
|
+
* @code{.c}
|
2628
|
+
* lcb_CMDDIAG cmd = { 0 };
|
2629
|
+
* lcb_diag(instance, fp, &cmd);
|
2630
|
+
* lcb_wait(instance);
|
2631
|
+
* @endcode
|
2632
|
+
*
|
2633
|
+
* @par Response
|
2634
|
+
* @code{.c}
|
2635
|
+
* lcb_install_callback3(instance, LCB_CALLBACK_DIAG, diag_callback);
|
2636
|
+
* void diag_callback(lcb_t, int, const lcb_RESPBASE *rb)
|
2637
|
+
* {
|
2638
|
+
* const lcb_RESPDIAG *resp = (const lcb_RESPDIAG *)rb;
|
2639
|
+
* if (resp->rc != LCB_SUCCESS) {
|
2640
|
+
* fprintf(stderr, "failed: %s\n", lcb_strerror(NULL, resp->rc));
|
2641
|
+
* } else {
|
2642
|
+
* if (resp->njson) {
|
2643
|
+
* fprintf(stderr, "\n%.*s", (int)resp->njson, resp->json);
|
2644
|
+
* }
|
2645
|
+
* }
|
2646
|
+
* }
|
2647
|
+
* @endcode
|
2648
|
+
*
|
2649
|
+
* @param instance the library handle
|
2650
|
+
* @param cookie the cookie passed in the callback
|
2651
|
+
* @param cmd command structure.
|
2652
|
+
* @return status code for scheduling.
|
2653
|
+
*/
|
2654
|
+
LIBCOUCHBASE_API
|
2655
|
+
lcb_error_t lcb_diag(lcb_t instance, const void *cookie, const lcb_CMDDIAG *cmd);
|
2656
|
+
/**@} (Group: PING) */
|
2657
|
+
|
2658
|
+
/**@ingroup lcb-public-api
|
2659
|
+
* @defgroup lcb-http HTTP Client
|
2660
|
+
* @brief Access Couchbase HTTP APIs
|
2661
|
+
* @details The low-level HTTP client may be used to access various HTTP-based
|
2662
|
+
* Couchbase APIs.
|
2663
|
+
*
|
2664
|
+
* Note that existing higher level APIs can be used for N1QL queries (see
|
2665
|
+
* @ref lcb-n1ql-api) and MapReduce view queries (see @ref lcb-view-api)
|
2666
|
+
*
|
2667
|
+
* @addtogroup lcb-http
|
2668
|
+
* @{
|
2669
|
+
*/
|
2670
|
+
|
2671
|
+
/**
|
2672
|
+
* @brief The type of HTTP request to execute
|
2673
|
+
*/
|
2674
|
+
typedef enum {
|
2675
|
+
/**
|
2676
|
+
* Execute a request against the bucket. The handle must be of
|
2677
|
+
* @ref LCB_TYPE_BUCKET and must be connected.
|
2678
|
+
*/
|
2679
|
+
LCB_HTTP_TYPE_VIEW = 0,
|
2680
|
+
|
2681
|
+
/**
|
2682
|
+
* Execute a management API request. The credentials used will match
|
2683
|
+
* those passed during the instance creation time. Thus is the instance
|
2684
|
+
* type is @ref LCB_TYPE_BUCKET then only bucket-level credentials will
|
2685
|
+
* be used.
|
2686
|
+
*/
|
2687
|
+
LCB_HTTP_TYPE_MANAGEMENT = 1,
|
2688
|
+
|
2689
|
+
/**
|
2690
|
+
* Execute an arbitrary request against a host and port
|
2691
|
+
*/
|
2692
|
+
LCB_HTTP_TYPE_RAW = 2,
|
2693
|
+
|
2694
|
+
/** Execute an N1QL Query */
|
2695
|
+
LCB_HTTP_TYPE_N1QL = 3,
|
2696
|
+
|
2697
|
+
/** Search a fulltext index */
|
2698
|
+
LCB_HTTP_TYPE_FTS = 4,
|
2699
|
+
|
2700
|
+
/** Execute an Analytics Query */
|
2701
|
+
LCB_HTTP_TYPE_CBAS = 5,
|
2702
|
+
|
2703
|
+
/**
|
2704
|
+
* Special pseudo-type, for ping endpoints in various services.
|
2705
|
+
* Behaves like RAW (the lcb_ping3() function will setup custom path),
|
2706
|
+
* but supports Keep-Alive
|
2707
|
+
*/
|
2708
|
+
LCB_HTTP_TYPE_PING = 6,
|
2709
|
+
|
2710
|
+
LCB_HTTP_TYPE_MAX
|
2711
|
+
} lcb_http_type_t;
|
2712
|
+
|
2713
|
+
/**
|
2714
|
+
* @brief HTTP Request method enumeration
|
2715
|
+
* These just enumerate the various types of HTTP request methods supported.
|
2716
|
+
* Refer to the specific cluster or view API to see which method is appropriate
|
2717
|
+
* for your request
|
2718
|
+
*/
|
2719
|
+
typedef enum {
|
2720
|
+
LCB_HTTP_METHOD_GET = 0,
|
2721
|
+
LCB_HTTP_METHOD_POST = 1,
|
2722
|
+
LCB_HTTP_METHOD_PUT = 2,
|
2723
|
+
LCB_HTTP_METHOD_DELETE = 3,
|
2724
|
+
LCB_HTTP_METHOD_MAX = 4
|
2725
|
+
} lcb_http_method_t;
|
2726
|
+
|
2727
|
+
/**
|
2728
|
+
* Command flag for HTTP to indicate that the callback is to be invoked
|
2729
|
+
* multiple times for each new chunk of incoming data. Once the entire body
|
2730
|
+
* have been received, the callback will be invoked once more with the
|
2731
|
+
* LCB_RESP_F_FINAL flag (in lcb_RESPHTTP::rflags) and an empty content.
|
2732
|
+
*
|
2733
|
+
* To use streaming requests, this flag should be set in the
|
2734
|
+
* lcb_CMDHTTP::cmdflags field
|
2735
|
+
*/
|
2736
|
+
#define LCB_CMDHTTP_F_STREAM (1 << 16)
|
2737
|
+
|
2738
|
+
/**
|
2739
|
+
* @internal
|
2740
|
+
* If specified, the lcb_CMDHTTP::cas field becomes the timeout for this
|
2741
|
+
* specific request.
|
2742
|
+
*/
|
2743
|
+
#define LCB_CMDHTTP_F_CASTMO (1 << 17)
|
2744
|
+
|
2745
|
+
/**
|
2746
|
+
* @internal
|
2747
|
+
* Do not inject authentication header into the request.
|
2748
|
+
*/
|
2749
|
+
#define LCB_CMDHTTP_F_NOUPASS (1 << 18)
|
2750
|
+
|
2751
|
+
/**
|
2752
|
+
* Structure for performing an HTTP request.
|
2753
|
+
* Note that the key and nkey fields indicate the _path_ for the API
|
2754
|
+
*/
|
2755
|
+
typedef struct {
|
2756
|
+
LCB_CMD_BASE;
|
2757
|
+
/**Type of request to issue. LCB_HTTP_TYPE_VIEW will issue a request
|
2758
|
+
* against a random node's view API. LCB_HTTP_TYPE_MANAGEMENT will issue
|
2759
|
+
* a request against a random node's administrative API, and
|
2760
|
+
* LCB_HTTP_TYPE_RAW will issue a request against an arbitrary host. */
|
2761
|
+
lcb_http_type_t type;
|
2762
|
+
lcb_http_method_t method; /**< HTTP Method to use */
|
2763
|
+
|
2764
|
+
/** If the request requires a body (e.g. `PUT` or `POST`) then it will
|
2765
|
+
* go here. Be sure to indicate the length of the body too. */
|
2766
|
+
const char *body;
|
2767
|
+
|
2768
|
+
/** Length of the body for the request */
|
2769
|
+
lcb_SIZE nbody;
|
2770
|
+
|
2771
|
+
/** If non-NULL, will be assigned a handle which may be used to
|
2772
|
+
* subsequently cancel the request */
|
2773
|
+
lcb_http_request_t *reqhandle;
|
2774
|
+
|
2775
|
+
/** For views, set this to `application/json` */
|
2776
|
+
const char *content_type;
|
2777
|
+
|
2778
|
+
/** Username to authenticate with, if left empty, will use the credentials
|
2779
|
+
* passed to lcb_create() */
|
2780
|
+
const char *username;
|
2781
|
+
|
2782
|
+
/** Password to authenticate with, if left empty, will use the credentials
|
2783
|
+
* passed to lcb_create() */
|
2784
|
+
const char *password;
|
2785
|
+
|
2786
|
+
/** If set, this must be a string in the form of `http://host:port`. Should
|
2787
|
+
* only be used for raw requests. */
|
2788
|
+
const char *host;
|
2789
|
+
} lcb_CMDHTTP;
|
2790
|
+
|
2791
|
+
/**
|
2792
|
+
* Structure for HTTP responses.
|
2793
|
+
* Note that #rc being `LCB_SUCCESS` does not always indicate that the HTTP
|
2794
|
+
* request itself was successful. It only indicates that the outgoing request
|
2795
|
+
* was submitted to the server and the client received a well-formed HTTP
|
2796
|
+
* response. Check the #hstatus field to see the actual HTTP-level status
|
2797
|
+
* code received.
|
2798
|
+
*/
|
2799
|
+
typedef struct {
|
2800
|
+
LCB_RESP_BASE
|
2801
|
+
/**HTTP status code. The value is only valid if #rc is ::LCB_SUCCESS
|
2802
|
+
* (if #rc is not LCB_SUCCESS then this field may be 0 as the response may
|
2803
|
+
* have not been read/sent) */
|
2804
|
+
short htstatus;
|
2805
|
+
|
2806
|
+
/**List of key-value headers. This field itself may be `NULL`. The list
|
2807
|
+
* is terminated by a `NULL` pointer to indicate no more headers. */
|
2808
|
+
const char * const * headers;
|
2809
|
+
|
2810
|
+
/**If @ref LCB_CMDHTTP_F_STREAM is true, contains the current chunk
|
2811
|
+
* of response content. Otherwise, contains the entire response body.*/
|
2812
|
+
const void *body;
|
2813
|
+
/** Length of buffer in #body */
|
2814
|
+
lcb_SIZE nbody;
|
2815
|
+
/**@internal*/
|
2816
|
+
lcb_http_request_t _htreq;
|
2817
|
+
} lcb_RESPHTTP;
|
2818
|
+
|
2819
|
+
/**
|
2820
|
+
* @committed
|
2821
|
+
* Issue an HTTP API request.
|
2822
|
+
* @param instance the library handle
|
2823
|
+
* @param cookie cookie to be associated with the request
|
2824
|
+
* @param cmd the command
|
2825
|
+
* @return LCB_SUCCESS if the request was scheduled successfully.
|
2826
|
+
*
|
2827
|
+
*
|
2828
|
+
* @par Simple Response
|
2829
|
+
* @code{.c}
|
2830
|
+
* void http_callback(lcb_t, int, const lcb_RESPBASE *rb)
|
2831
|
+
* {
|
2832
|
+
* const lcb_RESPHTTP *resp = (const lcb_RESPHTTP *)rb;
|
2833
|
+
* if (resp->rc != LCB_SUCCESS) {
|
2834
|
+
* printf("I/O Error for HTTP: %s\n", lcb_strerror(NULL, resp->rc));
|
2835
|
+
* return;
|
2836
|
+
* }
|
2837
|
+
* printf("Got HTTP Status: %d\n", resp->htstatus);
|
2838
|
+
* printf("Got paylod: %.*s\n", (int)resp->nbody, resp->body);
|
2839
|
+
* const char **hdrp = resp->headers;
|
2840
|
+
* while (*hdrp != NULL) {
|
2841
|
+
* printf("%s: %s\n", hdrp[0], hdrp[1]);
|
2842
|
+
* hdrp += 2;
|
2843
|
+
* }
|
2844
|
+
* }
|
2845
|
+
* @endcode
|
2846
|
+
*
|
2847
|
+
* @par Streaming Response
|
2848
|
+
* If the @ref LCB_CMDHTTP_F_STREAM flag is set in lcb_CMDHTTP::cmdflags then the
|
2849
|
+
* response callback is invoked multiple times as data arrives off the socket.
|
2850
|
+
* @code{.c}
|
2851
|
+
* void http_strm_callback(lcb_t, int, const lcb_RESPBASE *rb)
|
2852
|
+
* {
|
2853
|
+
* const lcb_RESPHTTP *resp = (const lcb_RESPHTTP *)resp;
|
2854
|
+
* if (resp->rflags & LCB_RESP_F_FINAL) {
|
2855
|
+
* if (resp->rc != LCB_SUCCESS) {
|
2856
|
+
* // ....
|
2857
|
+
* }
|
2858
|
+
* const char **hdrp = resp->headers;
|
2859
|
+
* // ...
|
2860
|
+
* } else {
|
2861
|
+
* handle_body(resp->body, resp->nbody);
|
2862
|
+
* }
|
2863
|
+
* }
|
2864
|
+
* @endcode
|
2865
|
+
*
|
2866
|
+
* @par Connection Reuse
|
2867
|
+
* The library will attempt to reuse connections for frequently contacted hosts.
|
2868
|
+
* By default the library will keep one idle connection to each host for a maximum
|
2869
|
+
* of 10 seconds. The number of open idle HTTP connections can be controlled with
|
2870
|
+
* @ref LCB_CNTL_HTTP_POOLSIZE.
|
2871
|
+
*
|
2872
|
+
*/
|
2873
|
+
LIBCOUCHBASE_API
|
2874
|
+
lcb_error_t
|
2875
|
+
lcb_http3(lcb_t instance, const void *cookie, const lcb_CMDHTTP *cmd);
|
2876
|
+
|
2877
|
+
/**
|
2878
|
+
* @brief Cancel ongoing HTTP request
|
2879
|
+
*
|
2880
|
+
* This API will stop the current request. Any pending callbacks will not be
|
2881
|
+
* invoked any any pending data will not be delivered. Useful for a long running
|
2882
|
+
* request which is no longer needed
|
2883
|
+
*
|
2884
|
+
* @param instance The handle to lcb
|
2885
|
+
* @param request The request handle
|
2886
|
+
*
|
2887
|
+
* @committed
|
2888
|
+
*
|
2889
|
+
* @par Example
|
2890
|
+
* @code{.c}
|
2891
|
+
* lcb_CMDHTTP htcmd = { 0 };
|
2892
|
+
* populate_htcmd(&htcmd); // dummy function
|
2893
|
+
* lcb_http_request_t reqhandle;
|
2894
|
+
* htcmd.reqhandle = &reqhandle;
|
2895
|
+
* lcb_http3(instance, cookie, &htcmd);
|
2896
|
+
* do_stuff();
|
2897
|
+
* lcb_cancel_http_request(instance, reqhandle);
|
2898
|
+
* @endcode
|
2899
|
+
*/
|
2900
|
+
LIBCOUCHBASE_API
|
2901
|
+
void
|
2902
|
+
lcb_cancel_http_request(lcb_t instance, lcb_http_request_t request);
|
2903
|
+
/**@} (Group: HTTP) */
|
2904
|
+
|
2905
|
+
/**
|
2906
|
+
* @ingroup lcb-public-api
|
2907
|
+
* @defgroup lcb-cookie User Cookies
|
2908
|
+
* @brief Associate user-defined data with operations
|
2909
|
+
* @details
|
2910
|
+
*
|
2911
|
+
* User-defined pointers may be passed to all operations in the form of a
|
2912
|
+
* `cookie` parameter. This cookie parameter allows any kind of application
|
2913
|
+
* context to be accessible via the callback (in lcb_RESPBASE::cookie).
|
2914
|
+
*
|
2915
|
+
* The library will not inspect or manage the address or contents of the
|
2916
|
+
* cookie; it may live on the stack (especially if using the library
|
2917
|
+
* synchronously), on the heap, or may be NULL altogether.
|
2918
|
+
*
|
2919
|
+
* In addition to per-operation cookies, the library allows the instance itself
|
2920
|
+
* (i.e. the `lcb_t` object) to contain its own cookie. This is helpful when
|
2921
|
+
* there is a wrapper object which needs to be accessed from within the callback
|
2922
|
+
*
|
2923
|
+
* @addtogroup lcb-cookie
|
2924
|
+
* @{
|
2925
|
+
*/
|
2926
|
+
|
2927
|
+
/**
|
2928
|
+
* Associate a cookie with an instance of lcb. The _cookie_ is a user defined
|
2929
|
+
* pointer which will remain attached to the specified `lcb_t` for its duration.
|
2930
|
+
* This is the way to associate user data with the `lcb_t`.
|
2931
|
+
*
|
2932
|
+
* @param instance the instance to associate the cookie to
|
2933
|
+
* @param cookie the cookie to associate with this instance.
|
2934
|
+
*
|
2935
|
+
* @attention
|
2936
|
+
* There is no destructor for the specified `cookie` stored with the instance;
|
2937
|
+
* thus you must ensure to manually free resources to the pointer (if it was
|
2938
|
+
* dynamically allocated) when it is no longer required.
|
2939
|
+
* @committed
|
2940
|
+
*
|
2941
|
+
* @code{.c}
|
2942
|
+
* typedef struct {
|
2943
|
+
* const char *status;
|
2944
|
+
* // ....
|
2945
|
+
* } instance_info;
|
2946
|
+
*
|
2947
|
+
* static void bootstrap_callback(lcb_t instance, lcb_error_t err) {
|
2948
|
+
* instance_info *info = (instance_info *)lcb_get_cookie(instance);
|
2949
|
+
* if (err == LCB_SUCCESS) {
|
2950
|
+
* info->status = "Connected";
|
2951
|
+
* } else {
|
2952
|
+
* info->status = "Error";
|
2953
|
+
* }
|
2954
|
+
* }
|
2955
|
+
*
|
2956
|
+
* static void do_create(void) {
|
2957
|
+
* instance_info *info = calloc(1, sizeof(*info));
|
2958
|
+
* // info->status is currently NULL
|
2959
|
+
* // .. create the instance here
|
2960
|
+
* lcb_set_cookie(instance, info);
|
2961
|
+
* lcb_set_bootstrap_callback(instance, bootstrap_callback);
|
2962
|
+
* lcb_connect(instance);
|
2963
|
+
* lcb_wait(instance);
|
2964
|
+
* printf("Status of instance is %s\n", info->status);
|
2965
|
+
* }
|
2966
|
+
* @endcode
|
2967
|
+
*/
|
2968
|
+
LIBCOUCHBASE_API
|
2969
|
+
void lcb_set_cookie(lcb_t instance, const void *cookie);
|
2970
|
+
|
2971
|
+
/**
|
2972
|
+
* Retrieve the cookie associated with this instance
|
2973
|
+
* @param instance the instance of lcb
|
2974
|
+
* @return The cookie associated with this instance or NULL
|
2975
|
+
* @see lcb_set_cookie()
|
2976
|
+
* @committed
|
2977
|
+
*/
|
2978
|
+
LIBCOUCHBASE_API
|
2979
|
+
const void *lcb_get_cookie(lcb_t instance);
|
2980
|
+
/**@} (Group: Cookies) */
|
2981
|
+
|
2982
|
+
/**
|
2983
|
+
* @defgroup lcb-wait Waiting
|
2984
|
+
* @brief Functions for synchronous I/O execution
|
2985
|
+
* @details The lcb_wait() family of functions allow to control when the
|
2986
|
+
* library sends the operations to the cluster and waits for their execution.
|
2987
|
+
*
|
2988
|
+
* It is also possible to use non-blocking I/O with the library
|
2989
|
+
*
|
2990
|
+
* @addtogroup lcb-wait
|
2991
|
+
* @{
|
2992
|
+
*/
|
2993
|
+
|
2994
|
+
/**
|
2995
|
+
* @brief Wait for the execution of all batched requests
|
2996
|
+
*
|
2997
|
+
* A batched request is any request which requires network I/O.
|
2998
|
+
* This includes most of the APIs. You should _not_ use this API if you are
|
2999
|
+
* integrating with an asynchronous event loop (i.e. one where your application
|
3000
|
+
* code is invoked asynchronously via event loops).
|
3001
|
+
*
|
3002
|
+
* This function will block the calling thread until either
|
3003
|
+
*
|
3004
|
+
* * All operations have been completed
|
3005
|
+
* * lcb_breakout() is explicitly called
|
3006
|
+
*
|
3007
|
+
* @param instance the instance containing the requests
|
3008
|
+
* @return whether the wait operation failed, or LCB_SUCCESS
|
3009
|
+
* @committed
|
3010
|
+
*/
|
3011
|
+
LIBCOUCHBASE_API
|
3012
|
+
lcb_error_t lcb_wait(lcb_t instance);
|
3013
|
+
|
3014
|
+
/**
|
3015
|
+
* @volatile
|
3016
|
+
* This function will cause a single "tick" in the underlying event loop,
|
3017
|
+
* causing operations whose I/O can be executed immediately to be sent to
|
3018
|
+
* the server.
|
3019
|
+
*
|
3020
|
+
* Like lcb_wait(), callbacks for operations may be delivered here, however
|
3021
|
+
* some operations may be left incomplete if their I/O could not be processed
|
3022
|
+
* immediately. This function is intended as an optimization for large batches
|
3023
|
+
* of operations - so that some I/O can be completed during the batching process
|
3024
|
+
* itself, and only the remainder of those operations (which would have blocked)
|
3025
|
+
* will be completed with lcb_wait() (which should be invoked after the batch).
|
3026
|
+
*
|
3027
|
+
* This function is mainly useful if there is a significant delay in time
|
3028
|
+
* between each scheduling function, in which I/O may be completed during these
|
3029
|
+
* gaps (thereby emptying the socket's kernel write buffer, and allowing for
|
3030
|
+
* new operations to be added after the interval). Calling this function for
|
3031
|
+
* batches where all data is available up-front may actually make things slower.
|
3032
|
+
*
|
3033
|
+
* @warning
|
3034
|
+
* You must call lcb_wait() at least one after any batch of operations to ensure
|
3035
|
+
* they have been completed. This function is provided as an optimization only.
|
3036
|
+
*
|
3037
|
+
* @return LCB_CLIENT_FEATURE_UNAVAILABLE if the event loop does not support
|
3038
|
+
* the "tick" mode.
|
3039
|
+
*/
|
3040
|
+
LIBCOUCHBASE_API
|
3041
|
+
lcb_error_t lcb_tick_nowait(lcb_t instance);
|
3042
|
+
|
3043
|
+
/**@brief Flags for lcb_wait3()*/
|
3044
|
+
typedef enum {
|
3045
|
+
/**Behave like the old lcb_wait()*/
|
3046
|
+
LCB_WAIT_DEFAULT = 0x00,
|
3047
|
+
|
3048
|
+
/**Do not check pending operations before running the event loop. By default
|
3049
|
+
* lcb_wait() will traverse the server list to check if any operations are
|
3050
|
+
* pending, and if nothing is pending the function will return without
|
3051
|
+
* running the event loop. This is usually not necessary for applications
|
3052
|
+
* which already _only_ call lcb_wait() when they know they have scheduled
|
3053
|
+
* at least one command.
|
3054
|
+
*/
|
3055
|
+
LCB_WAIT_NOCHECK = 0x01
|
3056
|
+
} lcb_WAITFLAGS;
|
3057
|
+
|
3058
|
+
/**
|
3059
|
+
* @committed
|
3060
|
+
* @brief Wait for completion of scheduled operations.
|
3061
|
+
* @param instance the instance
|
3062
|
+
* @param flags flags to modify the behavior of lcb_wait(). Pass 0 to obtain
|
3063
|
+
* behavior identical to lcb_wait().
|
3064
|
+
*/
|
3065
|
+
LIBCOUCHBASE_API
|
3066
|
+
void lcb_wait3(lcb_t instance, lcb_WAITFLAGS flags);
|
3067
|
+
|
3068
|
+
/**
|
3069
|
+
* @brief Forcefully break from the event loop.
|
3070
|
+
*
|
3071
|
+
* You may call this function from within any callback to signal to the library
|
3072
|
+
* that it return control to the function calling lcb_wait() as soon as possible.
|
3073
|
+
* Note that if there are pending functions which have not been processed, you
|
3074
|
+
* are responsible for calling lcb_wait() a second time.
|
3075
|
+
*
|
3076
|
+
* @param instance the instance to run the event loop for.
|
3077
|
+
* @committed
|
3078
|
+
*/
|
3079
|
+
LIBCOUCHBASE_API
|
3080
|
+
void lcb_breakout(lcb_t instance);
|
3081
|
+
|
3082
|
+
/**
|
3083
|
+
* @brief Check if instance is blocked in the event loop
|
3084
|
+
* @param instance the instance to run the event loop for.
|
3085
|
+
* @return non-zero if nobody is waiting for IO interaction
|
3086
|
+
* @uncommitted
|
3087
|
+
*/
|
3088
|
+
LIBCOUCHBASE_API
|
3089
|
+
int lcb_is_waiting(lcb_t instance);
|
3090
|
+
/**@} (Group: Wait) */
|
3091
|
+
|
3092
|
+
/**
|
3093
|
+
* @uncommitted
|
3094
|
+
*
|
3095
|
+
* @brief Force the library to refetch the cluster configuration
|
3096
|
+
*
|
3097
|
+
* The library by default employs various heuristics to determine if a new
|
3098
|
+
* configuration is needed from the cluster. However there are some situations
|
3099
|
+
* in which an application may wish to force a refresh of the configuration:
|
3100
|
+
*
|
3101
|
+
* * If a specific node has been failed
|
3102
|
+
* over and the library has received a configuration in which there is no
|
3103
|
+
* master node for a given key, the library will immediately return the error
|
3104
|
+
* `LCB_NO_MATCHING_SERVER` for the given item and will not request a new
|
3105
|
+
* configuration. In this state, the client will not perform any network I/O
|
3106
|
+
* until a request has been made to it using a key that is mapped to a known
|
3107
|
+
* active node.
|
3108
|
+
*
|
3109
|
+
* * The library's heuristics may have failed to detect an error warranting
|
3110
|
+
* a configuration change, but the application either through its own
|
3111
|
+
* heuristics, or through an out-of-band channel knows that the configuration
|
3112
|
+
* has changed.
|
3113
|
+
*
|
3114
|
+
*
|
3115
|
+
* This function is provided as an aid to assist in such situations
|
3116
|
+
*
|
3117
|
+
* If you wish for your application to block until a new configuration is
|
3118
|
+
* received, you _must_ call lcb_wait3() with the LCB_WAIT_NO_CHECK flag as
|
3119
|
+
* this function call is not bound to a specific operation. Additionally there
|
3120
|
+
* is no status notification as to whether this operation succeeded or failed
|
3121
|
+
* (the configuration callback via lcb_set_configuration_callback() may
|
3122
|
+
* provide hints as to whether a configuration was received or not, but by no
|
3123
|
+
* means should be considered to be part of this function's control flow).
|
3124
|
+
*
|
3125
|
+
* In general the use pattern of this function is like so:
|
3126
|
+
*
|
3127
|
+
* @code{.c}
|
3128
|
+
* unsigned retries = 5;
|
3129
|
+
* lcb_error_t err;
|
3130
|
+
* do {
|
3131
|
+
* retries--;
|
3132
|
+
* err = lcb_get(instance, cookie, ncmds, cmds);
|
3133
|
+
* if (err == LCB_NO_MATCHING_SERVER) {
|
3134
|
+
* lcb_refresh_config(instance);
|
3135
|
+
* usleep(100000);
|
3136
|
+
* lcb_wait3(instance, LCB_WAIT_NO_CHECK);
|
3137
|
+
* } else {
|
3138
|
+
* break;
|
3139
|
+
* }
|
3140
|
+
* } while (retries);
|
3141
|
+
* if (err == LCB_SUCCESS) {
|
3142
|
+
* lcb_wait3(instance, 0); // equivalent to lcb_wait(instance);
|
3143
|
+
* } else {
|
3144
|
+
* printf("Tried multiple times to fetch the key, but its node is down\n");
|
3145
|
+
* }
|
3146
|
+
* @endcode
|
3147
|
+
*/
|
3148
|
+
LIBCOUCHBASE_API
|
3149
|
+
void
|
3150
|
+
lcb_refresh_config(lcb_t instance);
|
3151
|
+
|
3152
|
+
/**
|
3153
|
+
* @ingroup lcb-public-api
|
3154
|
+
* @defgroup lcb-sched Advanced Scheduling
|
3155
|
+
* @brief Additional functions for scheduling operations
|
3156
|
+
*
|
3157
|
+
* @details
|
3158
|
+
*
|
3159
|
+
* An application may spool multiple operations into the library with the
|
3160
|
+
* option of unspooling previously-spooled operations in case one of
|
3161
|
+
* the operations cannot be spooled. These semantics exist primarily to
|
3162
|
+
* support "all-or-nothing" scheduling found in the V2 API as well as in
|
3163
|
+
* some other wrapping SDKs.
|
3164
|
+
*
|
3165
|
+
* From version 2.4.0 to version 2.5.5, use of the explicit scheduling
|
3166
|
+
* API was mandatory to schedule operations. This API is optional since 2.5.6.
|
3167
|
+
*
|
3168
|
+
* The following operation APIs are low level entry points which create a
|
3169
|
+
* single operation. To use these operation APIs you should call the
|
3170
|
+
* lcb_sched_enter() which creates a virtual scope in which to create operations.
|
3171
|
+
*
|
3172
|
+
* For each of these operation APIs, the actual API call will insert the
|
3173
|
+
* created packet into a "Scheduling Queue" (this is done through
|
3174
|
+
* mcreq_sched_add() which is in mcreq.h). You may add as many items to this
|
3175
|
+
* scheduling queue as you would like.
|
3176
|
+
*
|
3177
|
+
* Note that an operation is only added to the queue if it was able to be
|
3178
|
+
* scheduled properly. If a scheduling failure occurred (for example, if a
|
3179
|
+
* configuration is missing, the command had invalid input, or memory allocation
|
3180
|
+
* failed) then the command will not be placed into the queue.
|
3181
|
+
*
|
3182
|
+
* Once all operations have been scheduled you can call
|
3183
|
+
* lcb_sched_leave() which will place all commands scheduled into the I/O
|
3184
|
+
* queue.
|
3185
|
+
*
|
3186
|
+
* If you wish to _discard_ all scheduled operations (for example, if one of
|
3187
|
+
* them errored, and your application cannot handle partial scheduling failures)
|
3188
|
+
* then you may call lcb_sched_fail() which will release all the resources
|
3189
|
+
* of the packets placed into the temporary queue.
|
3190
|
+
*
|
3191
|
+
* @par Behavior from version 2.5.6
|
3192
|
+
*
|
3193
|
+
* Starting from version 2.5.6, use of this API is optional. Scheduling functions
|
3194
|
+
* will now check if an empty call to lcb_sched_enter() is present. If no call
|
3195
|
+
* to lcb_sched_enter() is found then the library will implicitly call
|
3196
|
+
* lcb_sched_leave().
|
3197
|
+
*
|
3198
|
+
* @addtogroup lcb-sched
|
3199
|
+
* @{
|
3200
|
+
*/
|
3201
|
+
|
3202
|
+
/**
|
3203
|
+
* @brief Enter a scheduling context.
|
3204
|
+
*
|
3205
|
+
* @uncommitted
|
3206
|
+
*
|
3207
|
+
* A scheduling context is an ephemeral list of
|
3208
|
+
* commands issued to various servers. Operations (like lcb_get3(), lcb_store3())
|
3209
|
+
* place packets into the current context.
|
3210
|
+
*
|
3211
|
+
* The context mechanism allows you to efficiently pipeline and schedule multiple
|
3212
|
+
* operations of different types and quantities. The network is not touched
|
3213
|
+
* and nothing is scheduled until the context is exited.
|
3214
|
+
*
|
3215
|
+
* @param instance the instance
|
3216
|
+
*
|
3217
|
+
* @code{.c}
|
3218
|
+
* lcb_sched_enter(instance);
|
3219
|
+
* lcb_get3(...);
|
3220
|
+
* lcb_store3(...);
|
3221
|
+
* lcb_counter3(...);
|
3222
|
+
* lcb_sched_leave(instance);
|
3223
|
+
* lcb_wait3(instance, LCB_WAIT_NOCHECK);
|
3224
|
+
* @endcode
|
3225
|
+
*/
|
3226
|
+
LIBCOUCHBASE_API
|
3227
|
+
void lcb_sched_enter(lcb_t instance);
|
3228
|
+
|
3229
|
+
/**
|
3230
|
+
* @uncommitted
|
3231
|
+
*
|
3232
|
+
* @brief Leave the current scheduling context, scheduling the commands within the
|
3233
|
+
* context to be flushed to the network.
|
3234
|
+
*
|
3235
|
+
* @details This will initiate a network-level flush (depending on the I/O system)
|
3236
|
+
* to the network. For completion-based I/O systems this typically means
|
3237
|
+
* allocating a temporary write context to contain the buffer. If using a
|
3238
|
+
* completion-based I/O module (for example, Windows or libuv) then it is
|
3239
|
+
* recommended to limit the number of calls to one per loop iteration. If
|
3240
|
+
* limiting the number of calls to this function is not possible (for example,
|
3241
|
+
* if the legacy API is being used, or you wish to use implicit scheduling) then
|
3242
|
+
* the flushing may be decoupled from this function - see the documentation for
|
3243
|
+
* lcb_sched_flush().
|
3244
|
+
*
|
3245
|
+
* @param instance the instance
|
3246
|
+
*/
|
3247
|
+
LIBCOUCHBASE_API
|
3248
|
+
void lcb_sched_leave(lcb_t instance);
|
3249
|
+
|
3250
|
+
|
3251
|
+
/**
|
3252
|
+
* @uncommitted
|
3253
|
+
* @brief Fail all commands in the current scheduling context.
|
3254
|
+
*
|
3255
|
+
* The commands placed within the current
|
3256
|
+
* scheduling context are released and are never flushed to the network.
|
3257
|
+
* @param instance
|
3258
|
+
*
|
3259
|
+
* @warning
|
3260
|
+
* This function only affects commands which have a direct correspondence
|
3261
|
+
* to memcached packets. Currently these are commands scheduled by:
|
3262
|
+
*
|
3263
|
+
* * lcb_get3()
|
3264
|
+
* * lcb_rget3()
|
3265
|
+
* * lcb_unlock3()
|
3266
|
+
* * lcb_touch3()
|
3267
|
+
* * lcb_store3()
|
3268
|
+
* * lcb_counter3()
|
3269
|
+
* * lcb_remove3()
|
3270
|
+
* * lcb_stats3()
|
3271
|
+
* * lcb_observe3_ctxnew()
|
3272
|
+
* * lcb_observe_seqno3()
|
3273
|
+
*
|
3274
|
+
* Other commands are _compound_ commands and thus should be in their own
|
3275
|
+
* scheduling context.
|
3276
|
+
*/
|
3277
|
+
LIBCOUCHBASE_API
|
3278
|
+
void lcb_sched_fail(lcb_t instance);
|
3279
|
+
|
3280
|
+
/**
|
3281
|
+
* @committed
|
3282
|
+
* @brief Request commands to be flushed to the network
|
3283
|
+
*
|
3284
|
+
* By default, the library will implicitly request a flush to the network upon
|
3285
|
+
* every call to lcb_sched_leave().
|
3286
|
+
*
|
3287
|
+
* [ Note, this does not mean the items are flushed
|
3288
|
+
* and I/O is performed, but it means the relevant event loop watchers are
|
3289
|
+
* activated to perform the operations on the next iteration ]. If
|
3290
|
+
* @ref LCB_CNTL_SCHED_IMPLICIT_FLUSH
|
3291
|
+
* is disabled then this behavior is disabled and the
|
3292
|
+
* application must explicitly call lcb_sched_flush(). This may be considered
|
3293
|
+
* more performant in the cases where multiple discreet operations are scheduled
|
3294
|
+
* in an lcb_sched_enter()/lcb_sched_leave() pair. With implicit flush enabled,
|
3295
|
+
* each call to lcb_sched_leave() will possibly invoke system repeatedly.
|
3296
|
+
*/
|
3297
|
+
LIBCOUCHBASE_API
|
3298
|
+
void lcb_sched_flush(lcb_t instance);
|
3299
|
+
|
3300
|
+
/**@} (Group: Adanced Scheduling) */
|
3301
|
+
|
3302
|
+
/**@ingroup lcb-public-api
|
3303
|
+
* @defgroup lcb-destroy Destroying
|
3304
|
+
* @brief Library destruction routines
|
3305
|
+
* @addtogroup lcb-destroy
|
3306
|
+
* @{
|
3307
|
+
*/
|
3308
|
+
/**
|
3309
|
+
* Destroy (and release all allocated resources) an instance of lcb.
|
3310
|
+
* Using instance after calling destroy will most likely cause your
|
3311
|
+
* application to crash.
|
3312
|
+
*
|
3313
|
+
* Note that any pending operations will not have their callbacks invoked.
|
3314
|
+
*
|
3315
|
+
* @param instance the instance to destroy.
|
3316
|
+
* @committed
|
3317
|
+
*/
|
3318
|
+
LIBCOUCHBASE_API
|
3319
|
+
void lcb_destroy(lcb_t instance);
|
3320
|
+
|
3321
|
+
/**
|
3322
|
+
* @brief Callback received when instance is about to be destroyed
|
3323
|
+
* @param cookie cookie passed to lcb_destroy_async()
|
3324
|
+
*/
|
3325
|
+
typedef void (*lcb_destroy_callback)(const void *cookie);
|
3326
|
+
|
3327
|
+
/**
|
3328
|
+
* @brief Set the callback to be invoked when the instance is destroyed
|
3329
|
+
* asynchronously.
|
3330
|
+
* @return the previous callback.
|
3331
|
+
*/
|
3332
|
+
LIBCOUCHBASE_API
|
3333
|
+
lcb_destroy_callback
|
3334
|
+
lcb_set_destroy_callback(lcb_t, lcb_destroy_callback);
|
3335
|
+
/**
|
3336
|
+
* @brief Asynchronously schedule the destruction of an instance.
|
3337
|
+
*
|
3338
|
+
* This function provides a safe way for asynchronous environments to destroy
|
3339
|
+
* the lcb_t handle without worrying about reentrancy issues.
|
3340
|
+
*
|
3341
|
+
* @param instance
|
3342
|
+
* @param arg a pointer passed to the callback.
|
3343
|
+
*
|
3344
|
+
* While the callback and cookie are optional, they are very much recommended
|
3345
|
+
* for testing scenarios where you wish to ensure that all resources allocated
|
3346
|
+
* by the instance have been closed. Specifically when the callback is invoked,
|
3347
|
+
* all timers (save for the one actually triggering the destruction) and sockets
|
3348
|
+
* will have been closed.
|
3349
|
+
*
|
3350
|
+
* As with lcb_destroy() you may call this function only once. You may not
|
3351
|
+
* call this function together with lcb_destroy as the two are mutually
|
3352
|
+
* exclusive.
|
3353
|
+
*
|
3354
|
+
* If for whatever reason this function is being called in a synchronous
|
3355
|
+
* flow, lcb_wait() must be invoked in order for the destruction to take effect
|
3356
|
+
*
|
3357
|
+
* @see lcb_set_destroy_callback
|
3358
|
+
*
|
3359
|
+
* @committed
|
3360
|
+
*/
|
3361
|
+
LIBCOUCHBASE_API
|
3362
|
+
void lcb_destroy_async(lcb_t instance, const void *arg);
|
3363
|
+
/**@} (Group: Destroy) */
|
3364
|
+
|
3365
|
+
/**@}*/
|
3366
|
+
|
3367
|
+
/** @internal */
|
3368
|
+
#define LCB_DATATYPE_JSON 0x01
|
3369
|
+
|
3370
|
+
/** @internal */
|
3371
|
+
typedef enum { LCB_VALUE_RAW = 0x00, LCB_VALUE_F_JSON = 0x01, LCB_VALUE_F_SNAPPYCOMP = 0x02 } lcb_VALUEFLAGS;
|
3372
|
+
|
3373
|
+
|
3374
|
+
/**
|
3375
|
+
* @ingroup lcb-public-api
|
3376
|
+
* @defgroup lcb-cluster-status Cluster Information
|
3377
|
+
* @brief These functions return status information about the handle, the current
|
3378
|
+
* connection, and the number of nodes found within the cluster.
|
3379
|
+
*
|
3380
|
+
* @see lcb_cntl() for more functions to retrieve status info
|
3381
|
+
*
|
3382
|
+
* @addtogroup lcb-cluster-status
|
3383
|
+
* @{
|
3384
|
+
*/
|
3385
|
+
|
3386
|
+
/**@brief
|
3387
|
+
* Type of node to retrieve for the lcb_get_node() function
|
3388
|
+
*/
|
3389
|
+
typedef enum {
|
3390
|
+
/** Get an HTTP configuration (Rest API) node */
|
3391
|
+
LCB_NODE_HTCONFIG = 0x01,
|
3392
|
+
/** Get a data (memcached) node */
|
3393
|
+
LCB_NODE_DATA = 0x02,
|
3394
|
+
/** Get a view (CAPI) node */
|
3395
|
+
LCB_NODE_VIEWS = 0x04,
|
3396
|
+
/** Only return a node which is connected, or a node which is known to be up */
|
3397
|
+
LCB_NODE_CONNECTED = 0x08,
|
3398
|
+
|
3399
|
+
/** Specifying this flag adds additional semantics which instruct the library
|
3400
|
+
* to search additional resources to return a host, and finally,
|
3401
|
+
* if no host can be found, return the string
|
3402
|
+
* constant @ref LCB_GETNODE_UNAVAILABLE. */
|
3403
|
+
LCB_NODE_NEVERNULL = 0x10,
|
3404
|
+
|
3405
|
+
/** Equivalent to `LCB_NODE_HTCONFIG|LCB_NODE_CONNECTED` */
|
3406
|
+
LCB_NODE_HTCONFIG_CONNECTED = 0x09,
|
3407
|
+
|
3408
|
+
/**Equivalent to `LCB_NODE_HTCONFIG|LCB_NODE_NEVERNULL`.
|
3409
|
+
* When this is passed, some additional attempts may be made by the library
|
3410
|
+
* to return any kind of host, including searching the initial list of hosts
|
3411
|
+
* passed to the lcb_create() function. */
|
3412
|
+
LCB_NODE_HTCONFIG_ANY = 0x11
|
3413
|
+
} lcb_GETNODETYPE;
|
3414
|
+
|
3415
|
+
/** String constant returned by lcb_get_node() when the @ref LCB_NODE_NEVERNULL
|
3416
|
+
* flag is specified, and no node can be returned */
|
3417
|
+
#define LCB_GETNODE_UNAVAILABLE "invalid_host:0"
|
3418
|
+
|
3419
|
+
/**
|
3420
|
+
* @brief Return a string of `host:port` for a node of the given type.
|
3421
|
+
*
|
3422
|
+
* @param instance the instance from which to retrieve the node
|
3423
|
+
* @param type the type of node to return
|
3424
|
+
* @param index the node number if index is out of bounds it will be wrapped
|
3425
|
+
* around, thus there is never an invalid value for this parameter
|
3426
|
+
*
|
3427
|
+
* @return a string in the form of `host:port`. If LCB_NODE_NEVERNULL was specified
|
3428
|
+
* as an option in `type` then the string constant LCB_GETNODE_UNAVAILABLE is
|
3429
|
+
* returned. Otherwise `NULL` is returned if the type is unrecognized or the
|
3430
|
+
* LCB_NODE_CONNECTED option was specified and no connected node could be found
|
3431
|
+
* or a memory allocation failed.
|
3432
|
+
*
|
3433
|
+
* @note The index parameter is _ignored_ if `type` is
|
3434
|
+
* LCB_NODE_HTCONFIG|LCB_NODE_CONNECTED as there will always be only a single
|
3435
|
+
* HTTP bootstrap node.
|
3436
|
+
*
|
3437
|
+
* @code{.c}
|
3438
|
+
* const char *viewnode = lcb_get_node(instance, LCB_NODE_VIEWS, 0);
|
3439
|
+
* // Get the connected REST endpoint:
|
3440
|
+
* const char *restnode = lcb_get_node(instance, LCB_NODE_HTCONFIG|LCB_NODE_CONNECTED, 0);
|
3441
|
+
* if (!restnode) {
|
3442
|
+
* printf("Instance not connected via HTTP!\n");
|
3443
|
+
* }
|
3444
|
+
* @endcode
|
3445
|
+
*
|
3446
|
+
* Iterate over all the data nodes:
|
3447
|
+
* @code{.c}
|
3448
|
+
* unsigned ii;
|
3449
|
+
* for (ii = 0; ii < lcb_get_num_servers(instance); ii++) {
|
3450
|
+
* const char *kvnode = lcb_get_node(instance, LCB_NODE_DATA, ii);
|
3451
|
+
* if (kvnode) {
|
3452
|
+
* printf("KV node %s exists at index %u\n", kvnode, ii);
|
3453
|
+
* } else {
|
3454
|
+
* printf("No node for index %u\n", ii);
|
3455
|
+
* }
|
3456
|
+
* }
|
3457
|
+
* @endcode
|
3458
|
+
*
|
3459
|
+
* @committed
|
3460
|
+
*/
|
3461
|
+
LIBCOUCHBASE_API
|
3462
|
+
const char *
|
3463
|
+
lcb_get_node(lcb_t instance, lcb_GETNODETYPE type, unsigned index);
|
3464
|
+
|
3465
|
+
/**
|
3466
|
+
* @committed
|
3467
|
+
*
|
3468
|
+
* @brief Get the target server for a given key.
|
3469
|
+
*
|
3470
|
+
* This is a convenience function wrapping around the vBucket API which allows
|
3471
|
+
* you to retrieve the target node (the node which will be contacted) when
|
3472
|
+
* performing KV operations involving the key.
|
3473
|
+
*
|
3474
|
+
* @param instance the instance
|
3475
|
+
* @param key the key to use
|
3476
|
+
* @param nkey the length of the key
|
3477
|
+
* @return a string containing the hostname, or NULL on error.
|
3478
|
+
*
|
3479
|
+
* Since this is a convenience function, error details are not contained here
|
3480
|
+
* in favor of brevity. Use the full vBucket API for more powerful functions.
|
3481
|
+
*/
|
3482
|
+
LIBCOUCHBASE_API
|
3483
|
+
const char *
|
3484
|
+
lcb_get_keynode(lcb_t instance, const void *key, size_t nkey);
|
3485
|
+
|
3486
|
+
/**
|
3487
|
+
* @brief Get the number of the replicas in the cluster
|
3488
|
+
*
|
3489
|
+
* @param instance The handle to lcb
|
3490
|
+
* @return -1 if the cluster wasn't configured yet, and number of replicas
|
3491
|
+
* otherwise. This may be `0` if there are no replicas.
|
3492
|
+
* @committed
|
3493
|
+
*/
|
3494
|
+
LIBCOUCHBASE_API
|
3495
|
+
lcb_S32 lcb_get_num_replicas(lcb_t instance);
|
3496
|
+
|
3497
|
+
/**
|
3498
|
+
* @brief Get the number of the nodes in the cluster
|
3499
|
+
* @param instance The handle to lcb
|
3500
|
+
* @return -1 if the cluster wasn't configured yet, and number of nodes otherwise.
|
3501
|
+
* @committed
|
3502
|
+
*/
|
3503
|
+
LIBCOUCHBASE_API
|
3504
|
+
lcb_S32 lcb_get_num_nodes(lcb_t instance);
|
3505
|
+
|
3506
|
+
|
3507
|
+
/**
|
3508
|
+
* @brief Get a list of nodes in the cluster
|
3509
|
+
*
|
3510
|
+
* @return a NULL-terminated list of 0-terminated strings consisting of
|
3511
|
+
* node hostnames:admin_ports for the entire cluster.
|
3512
|
+
* The storage duration of this list is only valid until the
|
3513
|
+
* next call to a libcouchbase function and/or when returning control to
|
3514
|
+
* libcouchbase' event loop.
|
3515
|
+
*
|
3516
|
+
* @code{.c}
|
3517
|
+
* const char * const * curp = lcb_get_server_list(instance);
|
3518
|
+
* for (; *curp; curp++) {
|
3519
|
+
* printf("Have node %s\n", *curp);
|
3520
|
+
* }
|
3521
|
+
* @endcode
|
3522
|
+
* @committed
|
3523
|
+
*/
|
3524
|
+
LIBCOUCHBASE_API
|
3525
|
+
const char *const *lcb_get_server_list(lcb_t instance);
|
3526
|
+
|
3527
|
+
/**
|
3528
|
+
* @volatile
|
3529
|
+
* @brief Write a textual dump to a file.
|
3530
|
+
*
|
3531
|
+
* This function will inspect the various internal structures of the current
|
3532
|
+
* client handle (indicated by `instance`) and write the state information
|
3533
|
+
* to the file indicated by `fp`.
|
3534
|
+
* @param instance the handle to dump
|
3535
|
+
* @param fp the file to which the dump should be written
|
3536
|
+
* @param flags a set of modifiers (of @ref lcb_DUMPFLAGS) indicating what
|
3537
|
+
* information to dump. Note that a standard set of information is always
|
3538
|
+
* dumped, but by default more verbose information is hidden, and may be
|
3539
|
+
* enabled with these flags.
|
3540
|
+
*/
|
3541
|
+
LIBCOUCHBASE_API
|
3542
|
+
void
|
3543
|
+
lcb_dump(lcb_t instance, FILE *fp, lcb_U32 flags);
|
3544
|
+
/**@} (Group: Cluster Info) */
|
3545
|
+
|
3546
|
+
/**
|
3547
|
+
* @ingroup lcb-public-api
|
3548
|
+
* @defgroup lcb-cntl Settings
|
3549
|
+
* @brief Get/Set Library Options
|
3550
|
+
*
|
3551
|
+
* @details
|
3552
|
+
*
|
3553
|
+
* The lcb_cntl() function and its various helpers are the means by which to
|
3554
|
+
* modify settings within the library
|
3555
|
+
*
|
3556
|
+
* @addtogroup lcb-cntl
|
3557
|
+
* @see <cntl.h>
|
3558
|
+
* @{
|
3559
|
+
*/
|
3560
|
+
|
3561
|
+
/**
|
3562
|
+
* This function exposes an ioctl/fcntl-like interface to read and write
|
3563
|
+
* various configuration properties to and from an lcb_t handle.
|
3564
|
+
*
|
3565
|
+
* @param instance The instance to modify
|
3566
|
+
*
|
3567
|
+
* @param mode One of LCB_CNTL_GET (to retrieve a setting) or LCB_CNTL_SET
|
3568
|
+
* (to modify a setting). Note that not all configuration properties
|
3569
|
+
* support SET.
|
3570
|
+
*
|
3571
|
+
* @param cmd The specific command/property to modify. This is one of the
|
3572
|
+
* LCB_CNTL_* constants defined in this file. Note that it is safe
|
3573
|
+
* (and even recommanded) to use the raw numeric value (i.e.
|
3574
|
+
* to be backwards and forwards compatible with libcouchbase
|
3575
|
+
* versions), as they are not subject to change.
|
3576
|
+
*
|
3577
|
+
* Using the actual value may be useful in ensuring your application
|
3578
|
+
* will still compile with an older libcouchbase version (though
|
3579
|
+
* you may get a runtime error (see return) if the command is not
|
3580
|
+
* supported
|
3581
|
+
*
|
3582
|
+
* @param arg The argument passed to the configuration handler.
|
3583
|
+
* The actual type of this pointer is dependent on the
|
3584
|
+
* command in question. Typically for GET operations, the
|
3585
|
+
* value of 'arg' is set to the current configuration value;
|
3586
|
+
* and for SET operations, the current configuration is
|
3587
|
+
* updated with the contents of *arg.
|
3588
|
+
*
|
3589
|
+
* @return ::LCB_NOT_SUPPORTED if the code is unrecognized
|
3590
|
+
* @return ::LCB_EINVAL if there was a problem with the argument
|
3591
|
+
* (typically for LCB_CNTL_SET) other error codes depending on the command.
|
3592
|
+
*
|
3593
|
+
* The following error codes are returned if the ::LCB_CNTL_DETAILED_ERRCODES
|
3594
|
+
* are enabled.
|
3595
|
+
*
|
3596
|
+
* @return ::LCB_ECTL_UNKNOWN if the code is unrecognized
|
3597
|
+
* @return ::LCB_ECTL_UNSUPPMODE An invalid _mode_ was passed
|
3598
|
+
* @return ::LCB_ECTL_BADARG if the value was invalid
|
3599
|
+
*
|
3600
|
+
* @committed
|
3601
|
+
*
|
3602
|
+
* @see lcb_cntl_setu32()
|
3603
|
+
* @see lcb_cntl_string()
|
3604
|
+
*/
|
3605
|
+
LIBCOUCHBASE_API
|
3606
|
+
lcb_error_t lcb_cntl(lcb_t instance, int mode, int cmd, void *arg);
|
3607
|
+
|
3608
|
+
/**
|
3609
|
+
* Alternatively one may change configuration settings by passing a string key
|
3610
|
+
* and value. This may be used to provide a simple interface from a command
|
3611
|
+
* line or higher level language to allow the setting of specific key-value
|
3612
|
+
* pairs.
|
3613
|
+
*
|
3614
|
+
* The format for the value is dependent on the option passed, the following
|
3615
|
+
* value types exist:
|
3616
|
+
*
|
3617
|
+
* - **Timeval**. A _timeval_ value can either be specified as fractional
|
3618
|
+
* seconds (`"1.5"` for 1.5 seconds), or in microseconds (`"1500000"`). In
|
3619
|
+
* releases prior to libcouchbase 2.8, this was called _timeout_.
|
3620
|
+
* - **Number**. This is any valid numerical value. This may be signed or
|
3621
|
+
* unsigned depending on the setting.
|
3622
|
+
* - **Boolean**. This specifies a boolean. A true value is either a positive
|
3623
|
+
* numeric value (i.e. `"1"`) or the string `"true"`. A false value
|
3624
|
+
* is a zero (i.e. `"0"`) or the string `"false"`.
|
3625
|
+
* - **Float**. This is like a _Number_, but also allows fractional specification,
|
3626
|
+
* e.g. `"2.4"`.
|
3627
|
+
* - **String**. Arbitrary string as `char *`, e.g. for client identification
|
3628
|
+
* string.
|
3629
|
+
* - **Path**. File path.
|
3630
|
+
* - **FILE*, Path**. Set file stream pointer (lcb_cntl() style) or file path
|
3631
|
+
* (lcb_cntl_string() style).
|
3632
|
+
*
|
3633
|
+
* | Code | Name | Type |
|
3634
|
+
* |-----------------------------------------|---------------------------|-------------------|
|
3635
|
+
* |@ref LCB_CNTL_OP_TIMEOUT | `"operation_timeout"` | Timeval |
|
3636
|
+
* |@ref LCB_CNTL_VIEW_TIMEOUT | `"view_timeout"` | Timeval |
|
3637
|
+
* |@ref LCB_CNTL_N1QL_TIMEOUT | `"n1ql_timeout"` | Timeval |
|
3638
|
+
* |@ref LCB_CNTL_HTTP_TIMEOUT | `"http_timeout"` | Timeval |
|
3639
|
+
* |@ref LCB_CNTL_CONFIG_POLL_INTERVAL | `"config_poll_interval"` | Timeval |
|
3640
|
+
* |@ref LCB_CNTL_CONFERRTHRESH | `"error_thresh_count"` | Number (Positive) |
|
3641
|
+
* |@ref LCB_CNTL_CONFIGURATION_TIMEOUT | `"config_total_timeout"` | Timeval |
|
3642
|
+
* |@ref LCB_CNTL_CONFIG_NODE_TIMEOUT | `"config_node_timeout"` | Timeval |
|
3643
|
+
* |@ref LCB_CNTL_CONFDELAY_THRESH | `"error_thresh_delay"` | Timeval |
|
3644
|
+
* |@ref LCB_CNTL_DURABILITY_TIMEOUT | `"durability_timeout"` | Timeval |
|
3645
|
+
* |@ref LCB_CNTL_DURABILITY_INTERVAL | `"durability_interval"` | Timeval |
|
3646
|
+
* |@ref LCB_CNTL_RANDOMIZE_BOOTSTRAP_HOSTS | `"randomize_nodes"` | Boolean |
|
3647
|
+
* |@ref LCB_CNTL_CONFIGCACHE | `"config_cache"` | Path |
|
3648
|
+
* |@ref LCB_CNTL_DETAILED_ERRCODES | `"detailed_errcodes"` | Boolean |
|
3649
|
+
* |@ref LCB_CNTL_HTCONFIG_URLTYPE | `"http_urlmode"` | Number (enum #lcb_HTCONFIG_URLTYPE) |
|
3650
|
+
* |@ref LCB_CNTL_RETRY_BACKOFF | `"retry_backoff"` | Float |
|
3651
|
+
* |@ref LCB_CNTL_RETRY_INTERVAL | `"retry_interval"` | Timeval |
|
3652
|
+
* |@ref LCB_CNTL_HTTP_POOLSIZE | `"http_poolsize"` | Number |
|
3653
|
+
* |@ref LCB_CNTL_VBGUESS_PERSIST | `"vbguess_persist"` | Boolean |
|
3654
|
+
* |@ref LCB_CNTL_CONLOGGER_LEVEL | `"console_log_level"` | Number (enum #lcb_log_severity_t) |
|
3655
|
+
* |@ref LCB_CNTL_FETCH_MUTATION_TOKENS | `"fetch_mutation_tokens"` | Boolean |
|
3656
|
+
* |@ref LCB_CNTL_DURABILITY_MUTATION_TOKENS | `"dur_mutation_tokens"` | Boolean |
|
3657
|
+
* |@ref LCB_CNTL_TCP_NODELAY | `"tcp_nodelay"` | Boolean |
|
3658
|
+
* |@ref LCB_CNTL_CONLOGGER_FP | `"console_log_file"` | FILE*, Path |
|
3659
|
+
* |@ref LCB_CNTL_CLIENT_STRING | `"client_string"` | String |
|
3660
|
+
* |@ref LCB_CNTL_TCP_KEEPALIVE | `"tcp_keepalive"` | Boolean |
|
3661
|
+
* |@ref LCB_CNTL_CONFIG_POLL_INTERVAL | `"config_poll_interval"` | Timeval |
|
3662
|
+
* |@ref LCB_CNTL_IP6POLICY | `"ipv6"` | String ("disabled", "only", "allow") |
|
3663
|
+
*
|
3664
|
+
* @committed - Note, the actual API call is considered committed and will
|
3665
|
+
* not disappear, however the existence of the various string settings are
|
3666
|
+
* dependendent on the actual settings they map to. It is recommended that
|
3667
|
+
* applications use the numerical lcb_cntl() as the string names are
|
3668
|
+
* subject to change.
|
3669
|
+
*
|
3670
|
+
* @see lcb_cntl()
|
3671
|
+
* @see lcb-cntl-settings
|
3672
|
+
*/
|
3673
|
+
LIBCOUCHBASE_API
|
3674
|
+
lcb_error_t
|
3675
|
+
lcb_cntl_string(lcb_t instance, const char *key, const char *value);
|
3676
|
+
|
3677
|
+
/**
|
3678
|
+
* @brief Convenience function to set a value as an lcb_U32
|
3679
|
+
* @param instance
|
3680
|
+
* @param cmd setting to modify
|
3681
|
+
* @param arg the new value
|
3682
|
+
* @return see lcb_cntl() for details
|
3683
|
+
* @committed
|
3684
|
+
*/
|
3685
|
+
LIBCOUCHBASE_API
|
3686
|
+
lcb_error_t lcb_cntl_setu32(lcb_t instance, int cmd, lcb_U32 arg);
|
3687
|
+
|
3688
|
+
/**
|
3689
|
+
* @brief Retrieve an lcb_U32 setting
|
3690
|
+
* @param instance
|
3691
|
+
* @param cmd setting to retrieve
|
3692
|
+
* @return the value.
|
3693
|
+
* @warning This function does not return an error code. Ensure that the cntl is
|
3694
|
+
* correct for this version, or use lcb_cntl() directly.
|
3695
|
+
* @committed
|
3696
|
+
*/
|
3697
|
+
LIBCOUCHBASE_API
|
3698
|
+
lcb_U32 lcb_cntl_getu32(lcb_t instance, int cmd);
|
3699
|
+
|
3700
|
+
/**
|
3701
|
+
* Determine if a specific control code exists
|
3702
|
+
* @param ctl the code to check for
|
3703
|
+
* @return 0 if it does not exist, nonzero if it exists.
|
3704
|
+
*/
|
3705
|
+
LIBCOUCHBASE_API
|
3706
|
+
int
|
3707
|
+
lcb_cntl_exists(int ctl);
|
3708
|
+
/**@}*/ /* settings */
|
3709
|
+
|
3710
|
+
/**
|
3711
|
+
* @ingroup lcb-public-api
|
3712
|
+
* @defgroup lcb-timings Timings
|
3713
|
+
* @brief Determine how long operations are taking to be completed
|
3714
|
+
*
|
3715
|
+
* libcouchbase provides a simple form of per-command timings you may use
|
3716
|
+
* to figure out the current lantency for the request-response cycle as
|
3717
|
+
* generated by your application. Please note that these numbers are not
|
3718
|
+
* necessarily accurate as you may affect the timing recorded by doing
|
3719
|
+
* work in the event loop.
|
3720
|
+
*
|
3721
|
+
* The time recorded with this library is the time elapsed from the
|
3722
|
+
* command being called, and the response packet being received from the
|
3723
|
+
* server. Everything the application does before driving the event loop
|
3724
|
+
* will affect the timers.
|
3725
|
+
*
|
3726
|
+
* The function lcb_enable_timings() is used to enable the timings for
|
3727
|
+
* the given instance, and lcb_disable_timings is used to disable the
|
3728
|
+
* timings. The overhead of using the timers should be negligible.
|
3729
|
+
*
|
3730
|
+
* The function lcb_get_timings is used to retrieve the current timing.
|
3731
|
+
* values from the given instance. The cookie is passed transparently to
|
3732
|
+
* the callback function.
|
3733
|
+
*
|
3734
|
+
* Here is an example of the usage of this module:
|
3735
|
+
*
|
3736
|
+
* @code{.c}
|
3737
|
+
* #include <libcouchbase/couchbase.h>
|
3738
|
+
*
|
3739
|
+
* static void callback(
|
3740
|
+
* lcb_t instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min,
|
3741
|
+
* lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)
|
3742
|
+
* {
|
3743
|
+
* FILE* out = (void*)cookie;
|
3744
|
+
* int num = (float)10.0 * (float)total / ((float)maxtotal);
|
3745
|
+
* fprintf(out, "[%3u - %3u]", min, max);
|
3746
|
+
* switch (timeunit) {
|
3747
|
+
* case LCB_TIMEUNIT_NSEC:
|
3748
|
+
* fprintf(out, "ns");
|
3749
|
+
* break;
|
3750
|
+
* case LCB_TIMEUNIT_USEC:
|
3751
|
+
* fprintf(out, "us");
|
3752
|
+
* break;
|
3753
|
+
* case LCB_TIMEUNIT_MSEC:
|
3754
|
+
* fsprintf(out, "ms");
|
3755
|
+
* break;
|
3756
|
+
* case LCB_TIMEUNIT_SEC:
|
3757
|
+
* fprintf(out, "s ");
|
3758
|
+
* break;
|
3759
|
+
* default:
|
3760
|
+
* ;
|
3761
|
+
* }
|
3762
|
+
*
|
3763
|
+
* fprintf(out, " |");
|
3764
|
+
* for (int ii = 0; ii < num; ++ii) {
|
3765
|
+
* fprintf(out, "#");
|
3766
|
+
* }
|
3767
|
+
* fprintf(out, " - %u\n", total);
|
3768
|
+
* }
|
3769
|
+
*
|
3770
|
+
*
|
3771
|
+
* lcb_enable_timings(instance);
|
3772
|
+
* ... do a lot of operations ...
|
3773
|
+
* fprintf(stderr, " +---------+\n"
|
3774
|
+
* lcb_get_timings(instance, stderr, callback);
|
3775
|
+
* fprintf(stderr, " +---------+\n"
|
3776
|
+
* lcb_disable_timings(instance);
|
3777
|
+
* @endcode
|
3778
|
+
*
|
3779
|
+
* @addtogroup lcb-timings
|
3780
|
+
* @{
|
3781
|
+
*/
|
3782
|
+
|
3783
|
+
/**
|
3784
|
+
* @brief Time units reported by lcb_get_timings()
|
3785
|
+
*/
|
3786
|
+
enum lcb_timeunit_t {
|
3787
|
+
LCB_TIMEUNIT_NSEC = 0, /**< @brief Time is in nanoseconds */
|
3788
|
+
LCB_TIMEUNIT_USEC = 1, /**< @brief Time is in microseconds */
|
3789
|
+
LCB_TIMEUNIT_MSEC = 2, /**< @brief Time is in milliseconds */
|
3790
|
+
LCB_TIMEUNIT_SEC = 3 /**< @brief Time is in seconds */
|
3791
|
+
};
|
3792
|
+
typedef enum lcb_timeunit_t lcb_timeunit_t;
|
3793
|
+
|
3794
|
+
/**
|
3795
|
+
* Start recording timing metrics for the different operations.
|
3796
|
+
* The timer is started when the command is called (and the data
|
3797
|
+
* spooled to the server), and the execution time is the time until
|
3798
|
+
* we parse the response packets. This means that you can affect
|
3799
|
+
* the timers by doing a lot of other stuff before checking if
|
3800
|
+
* there is any results available..
|
3801
|
+
*
|
3802
|
+
* @param instance the handle to lcb
|
3803
|
+
* @return Status of the operation.
|
3804
|
+
* @committed
|
3805
|
+
*/
|
3806
|
+
LIBCOUCHBASE_API
|
3807
|
+
lcb_error_t lcb_enable_timings(lcb_t instance);
|
3808
|
+
|
3809
|
+
|
3810
|
+
/**
|
3811
|
+
* Stop recording (and release all resources from previous measurements)
|
3812
|
+
* timing metrics.
|
3813
|
+
*
|
3814
|
+
* @param instance the handle to lcb
|
3815
|
+
* @return Status of the operation.
|
3816
|
+
* @committed
|
3817
|
+
*/
|
3818
|
+
LIBCOUCHBASE_API
|
3819
|
+
lcb_error_t lcb_disable_timings(lcb_t instance);
|
3820
|
+
|
3821
|
+
/**
|
3822
|
+
* The following function is called for each bucket in the timings
|
3823
|
+
* histogram when you call lcb_get_timings.
|
3824
|
+
* You are guaranteed that the callback will be called with the
|
3825
|
+
* lowest [min,max] range first.
|
3826
|
+
*
|
3827
|
+
* @param instance the handle to lcb
|
3828
|
+
* @param cookie the cookie you provided that allows you to pass
|
3829
|
+
* arbitrary user data to the callback
|
3830
|
+
* @param timeunit the "scale" for the values
|
3831
|
+
* @param min The lower bound for this histogram bucket
|
3832
|
+
* @param max The upper bound for this histogram bucket
|
3833
|
+
* @param total The number of hits in this histogram bucket
|
3834
|
+
* @param maxtotal The highest value in all of the buckets
|
3835
|
+
*/
|
3836
|
+
typedef void (*lcb_timings_callback)(lcb_t instance,
|
3837
|
+
const void *cookie,
|
3838
|
+
lcb_timeunit_t timeunit,
|
3839
|
+
lcb_U32 min,
|
3840
|
+
lcb_U32 max,
|
3841
|
+
lcb_U32 total,
|
3842
|
+
lcb_U32 maxtotal);
|
3843
|
+
|
3844
|
+
/**
|
3845
|
+
* Get the timings histogram
|
3846
|
+
*
|
3847
|
+
* @param instance the handle to lcb
|
3848
|
+
* @param cookie a cookie that will be present in all of the callbacks
|
3849
|
+
* @param callback Callback to invoke which will handle the timings
|
3850
|
+
* @return Status of the operation.
|
3851
|
+
* @committed
|
3852
|
+
*/
|
3853
|
+
LIBCOUCHBASE_API
|
3854
|
+
lcb_error_t lcb_get_timings(lcb_t instance,
|
3855
|
+
const void *cookie,
|
3856
|
+
lcb_timings_callback callback);
|
3857
|
+
/**@} (Group: Timings) */
|
3858
|
+
|
3859
|
+
/**
|
3860
|
+
* @ingroup lcb-public-api
|
3861
|
+
* @defgroup lcb-build-info Build Information
|
3862
|
+
* @brief Get library version and supported features
|
3863
|
+
* @details
|
3864
|
+
* These functions and macros may be used to conditionally compile features
|
3865
|
+
* depending on the version of the library being used. They may also be used
|
3866
|
+
* to employ various features at runtime and to retrieve the version for
|
3867
|
+
* informational purposes.
|
3868
|
+
* @addtogroup lcb-build-info
|
3869
|
+
* @{
|
3870
|
+
*/
|
3871
|
+
|
3872
|
+
#if !defined(LCB_VERSION_STRING) || defined(__LCB_DOXYGEN__)
|
3873
|
+
/** @brief libcouchbase version string */
|
3874
|
+
#define LCB_VERSION_STRING "unknown"
|
3875
|
+
#endif
|
3876
|
+
|
3877
|
+
#if !defined(LCB_VERSION) || defined(__LCB_DOXYGEN__)
|
3878
|
+
/**@brief libcouchbase hex version
|
3879
|
+
*
|
3880
|
+
* This number contains the hexadecimal representation of the library version.
|
3881
|
+
* It is in a format of `0xXXYYZZ` where `XX` is the two digit major version
|
3882
|
+
* (e.g. `02`), `YY` is the minor version (e.g. `05`) and `ZZ` is the patch
|
3883
|
+
* version (e.g. `24`).
|
3884
|
+
*
|
3885
|
+
* For example:
|
3886
|
+
*
|
3887
|
+
* String |Hex
|
3888
|
+
* ---------|---------
|
3889
|
+
* 2.0.0 | 0x020000
|
3890
|
+
* 2.1.3 | 0x020103
|
3891
|
+
* 3.0.15 | 0x030015
|
3892
|
+
*/
|
3893
|
+
#define LCB_VERSION 0x000000
|
3894
|
+
#endif
|
3895
|
+
|
3896
|
+
#if !defined(LCB_VERSION_CHANGESET) || defined(__LCB_DOXYGEN__)
|
3897
|
+
/**@brief The SCM revision ID. @see LCB_CNTL_CHANGESET */
|
3898
|
+
#define LCB_VERSION_CHANGESET "0xdeadbeef"
|
3899
|
+
#endif
|
3900
|
+
|
3901
|
+
/**
|
3902
|
+
* Get the version of the library.
|
3903
|
+
*
|
3904
|
+
* @param version where to store the numeric representation of the
|
3905
|
+
* version (or NULL if you don't care)
|
3906
|
+
*
|
3907
|
+
* @return the textual description of the version ('\0'
|
3908
|
+
* terminated). Do <b>not</b> try to release this string.
|
3909
|
+
*
|
3910
|
+
*/
|
3911
|
+
LIBCOUCHBASE_API
|
3912
|
+
const char *lcb_get_version(lcb_U32 *version);
|
3913
|
+
|
3914
|
+
/** Global/extern variable containing the version of the library */
|
3915
|
+
LIBCOUCHBASE_API LCB_EXTERN_VAR
|
3916
|
+
const lcb_U32 lcb_version_g;
|
3917
|
+
|
3918
|
+
/**@brief Whether the library has SSL support*/
|
3919
|
+
#define LCB_SUPPORTS_SSL 1
|
3920
|
+
/**@brief Whether the library has experimental compression support */
|
3921
|
+
#define LCB_SUPPORTS_SNAPPY 2
|
3922
|
+
/**@brief Whether the library has experimental tracing support */
|
3923
|
+
#define LCB_SUPPORTS_TRACING 3
|
3924
|
+
|
3925
|
+
/**
|
3926
|
+
* @committed
|
3927
|
+
* Determine if this version has support for a particularl feature
|
3928
|
+
* @param n the feature ID to check for
|
3929
|
+
* @return 0 if not supported, nonzero if supported.
|
3930
|
+
*/
|
3931
|
+
LIBCOUCHBASE_API
|
3932
|
+
int
|
3933
|
+
lcb_supports_feature(int n);
|
3934
|
+
|
3935
|
+
/**@} (Group: Build Info) */
|
3936
|
+
|
3937
|
+
|
3938
|
+
/**
|
3939
|
+
* Functions to allocate and free memory related to libcouchbase. This is
|
3940
|
+
* mainly for use on Windows where it is possible that the DLL and EXE
|
3941
|
+
* are using two different CRTs
|
3942
|
+
*/
|
3943
|
+
LIBCOUCHBASE_API
|
3944
|
+
void *lcb_mem_alloc(lcb_SIZE size);
|
3945
|
+
|
3946
|
+
/** Use this to free memory allocated with lcb_mem_alloc */
|
3947
|
+
LIBCOUCHBASE_API
|
3948
|
+
void lcb_mem_free(void *ptr);
|
3949
|
+
|
3950
|
+
/**
|
3951
|
+
* @internal
|
3952
|
+
*
|
3953
|
+
* These two functions unconditionally start and stop the event loop. These
|
3954
|
+
* should be used _only_ when necessary. Use lcb_wait and lcb_breakout
|
3955
|
+
* for safer variants.
|
3956
|
+
*
|
3957
|
+
* Internally these proxy to the run_event_loop/stop_event_loop calls
|
3958
|
+
*/
|
3959
|
+
LCB_INTERNAL_API
|
3960
|
+
void lcb_run_loop(lcb_t instance);
|
3961
|
+
|
3962
|
+
/** @internal */
|
3963
|
+
LCB_INTERNAL_API
|
3964
|
+
void lcb_stop_loop(lcb_t instance);
|
3965
|
+
|
3966
|
+
/** @internal */
|
3967
|
+
/* This returns the library's idea of time */
|
3968
|
+
LCB_INTERNAL_API
|
3969
|
+
lcb_U64 lcb_nstime(void);
|
3970
|
+
|
3971
|
+
typedef enum {
|
3972
|
+
/** Dump the raw vbucket configuration */
|
3973
|
+
LCB_DUMP_VBCONFIG = 0x01,
|
3974
|
+
/** Dump information about each packet */
|
3975
|
+
LCB_DUMP_PKTINFO = 0x02,
|
3976
|
+
/** Dump memory usage/reservation information about buffers */
|
3977
|
+
LCB_DUMP_BUFINFO = 0x04,
|
3978
|
+
/** Dump various metrics information */
|
3979
|
+
LCB_DUMP_METRICS = 0x08,
|
3980
|
+
/** Dump everything */
|
3981
|
+
LCB_DUMP_ALL = 0xff
|
3982
|
+
} lcb_DUMPFLAGS;
|
3983
|
+
|
3984
|
+
/** Volatile histogram APIs, used by pillowfight and others */
|
3985
|
+
struct lcb_histogram_st;
|
3986
|
+
typedef struct lcb_histogram_st lcb_HISTOGRAM;
|
3987
|
+
|
3988
|
+
/**
|
3989
|
+
* @volatile
|
3990
|
+
* Create a histogram structure
|
3991
|
+
* @return a new histogram structure
|
3992
|
+
*/
|
3993
|
+
LIBCOUCHBASE_API
|
3994
|
+
lcb_HISTOGRAM *
|
3995
|
+
lcb_histogram_create(void);
|
3996
|
+
|
3997
|
+
/**
|
3998
|
+
* @volatile free a histogram structure
|
3999
|
+
* @param hg the histogram
|
4000
|
+
*/
|
4001
|
+
LIBCOUCHBASE_API
|
4002
|
+
void
|
4003
|
+
lcb_histogram_destroy(lcb_HISTOGRAM *hg);
|
4004
|
+
|
4005
|
+
/**
|
4006
|
+
* @volatile
|
4007
|
+
* Add an entry to a histogram structure
|
4008
|
+
* @param hg the histogram
|
4009
|
+
* @param duration the duration in nanoseconds
|
4010
|
+
*/
|
4011
|
+
LIBCOUCHBASE_API
|
4012
|
+
void
|
4013
|
+
lcb_histogram_record(lcb_HISTOGRAM *hg, lcb_U64 duration);
|
4014
|
+
|
4015
|
+
typedef void (*lcb_HISTOGRAM_CALLBACK)
|
4016
|
+
(const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max,
|
4017
|
+
lcb_U32 total, lcb_U32 maxtotal);
|
4018
|
+
|
4019
|
+
/**
|
4020
|
+
* @volatile
|
4021
|
+
* Repeatedly invoke a callback for all entries in the histogram
|
4022
|
+
* @param hg the histogram
|
4023
|
+
* @param cookie pointer passed to callback
|
4024
|
+
* @param cb callback to invoke
|
4025
|
+
*/
|
4026
|
+
LIBCOUCHBASE_API
|
4027
|
+
void
|
4028
|
+
lcb_histogram_read(const lcb_HISTOGRAM *hg, const void *cookie,
|
4029
|
+
lcb_HISTOGRAM_CALLBACK cb);
|
4030
|
+
|
4031
|
+
/**
|
4032
|
+
* Print the histogram to the specified FILE.
|
4033
|
+
*
|
4034
|
+
* This essentially outputs the same raw information as lcb_histogram_read(),
|
4035
|
+
* except it prints in implementation-defined format. It's simpler to use
|
4036
|
+
* than lcb_histogram_read, but less flexible.
|
4037
|
+
*
|
4038
|
+
* @param hg the histogram
|
4039
|
+
* @param stream File to print the histogram to.
|
4040
|
+
*/
|
4041
|
+
LIBCOUCHBASE_API
|
4042
|
+
void lcb_histogram_print(lcb_HISTOGRAM* hg, FILE* stream);
|
4043
|
+
|
4044
|
+
/**
|
4045
|
+
* @volatile
|
4046
|
+
*
|
4047
|
+
* Retrieves the extra error context from the response structure.
|
4048
|
+
*
|
4049
|
+
* This context does not duplicate information described by status
|
4050
|
+
* code rendered by lcb_strerror() function, and should be logged
|
4051
|
+
* if available.
|
4052
|
+
*
|
4053
|
+
* @return the pointer to string or NULL if context wasn't specified.
|
4054
|
+
*/
|
4055
|
+
LIBCOUCHBASE_API
|
4056
|
+
const char *
|
4057
|
+
lcb_resp_get_error_context(int cbtype, const lcb_RESPBASE *rb);
|
4058
|
+
|
4059
|
+
/**
|
4060
|
+
* @uncommitted
|
4061
|
+
*
|
4062
|
+
* Retrieves the error reference id from the response structure.
|
4063
|
+
*
|
4064
|
+
* Error reference id (or event id) should be logged to allow
|
4065
|
+
* administrators match client-side events with cluster logs.
|
4066
|
+
*
|
4067
|
+
* @return the pointer to string or NULL if ref wasn't specified.
|
4068
|
+
*/
|
4069
|
+
LIBCOUCHBASE_API
|
4070
|
+
const char *
|
4071
|
+
lcb_resp_get_error_ref(int cbtype, const lcb_RESPBASE *rb);
|
4072
|
+
|
4073
|
+
/**
|
4074
|
+
* @volatile
|
4075
|
+
* Returns whether the library redacting logs for this connection instance.
|
4076
|
+
*
|
4077
|
+
* @return non-zero if the logs are being redacted for this instance.
|
4078
|
+
*/
|
4079
|
+
LIBCOUCHBASE_API
|
4080
|
+
int lcb_is_redacting_logs(lcb_t instance);
|
4081
|
+
|
4082
|
+
/* Post-include some other headers */
|
4083
|
+
#ifdef __cplusplus
|
4084
|
+
}
|
4085
|
+
#endif /* __cplusplus */
|
4086
|
+
#include <libcouchbase/subdoc.h>
|
4087
|
+
#include <libcouchbase/deprecated.h>
|
4088
|
+
#include <libcouchbase/api-legacy.h>
|
4089
|
+
#endif /* LIBCOUCHBASE_COUCHBASE_H */
|