From 54f01e08b61f4463a9659da7b329c7de04a41dce Mon Sep 17 00:00:00 2001 From: Brian Aker Date: Sat, 9 Apr 2011 21:55:10 -0700 Subject: [PATCH] Cleanup API documentation. --- docs/libmemcached_configuration.rst | 50 ++++++++++++++++- docs/libmemcached_examples.rst | 24 ++------- docs/man/libmemcached_examples.3 | 22 ++------ docs/man/memcached_clone.3 | 5 +- docs/man/memcached_create.3 | 5 +- docs/man/memcached_free.3 | 5 +- docs/man/memcached_servers_reset.3 | 5 +- docs/memcached_create.rst | 12 ++--- libmemcached/memcached.c | 27 ++++++++-- libmemcached/memcached.h | 2 +- libmemcached/options.h | 8 +-- tests/mem_functions.c | 1 - tests/parser.cc | 83 +++++++++++++++-------------- tests/parser.h | 3 -- 14 files changed, 138 insertions(+), 114 deletions(-) diff --git a/docs/libmemcached_configuration.rst b/docs/libmemcached_configuration.rst index 5cb35374..a6b4b606 100644 --- a/docs/libmemcached_configuration.rst +++ b/docs/libmemcached_configuration.rst @@ -2,7 +2,28 @@ Configuring Libmemcached ======================== -Libmemcached implements a custom language for configuring and modifying servers. +-------- +SYNOPSIS +-------- + + +.. c:function:: memcached_st *memcached_create_with_options(const char *string, size_t string_length) + + +.. c:function:: memcached_return_t libmemcached_check_configuration(const char *option_string, size_t length, char *error_buffer, size_t error_buffer_size) + +Compile and link with -lmemcached + + + +----------- +DESCRIPTION +----------- + +Libmemcached implements a custom language for configuring and modifying +servers. By passing in an option string you can generate a memcached_st object +that you can use in your application directly. + .. describe:: --SERVER=:/? @@ -121,3 +142,30 @@ End configutation processing. .. describe:: ERROR End configutation processing and throw an error. + + +------ +RETURN +------ + + +memcached_create_with_options() returns a pointer to the memcached_st that was +created (or initialized). On an allocation failure, it returns NULL. + + +---- +HOME +---- + + +To find out more information please check: +`https://launchpad.net/libmemcached `_ + + + +-------- +SEE ALSO +-------- + + +:manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` diff --git a/docs/libmemcached_examples.rst b/docs/libmemcached_examples.rst index 38d6f7b5..922ee143 100644 --- a/docs/libmemcached_examples.rst +++ b/docs/libmemcached_examples.rst @@ -40,31 +40,15 @@ Connecting to servers .. code-block:: c - memcached_server_st *servers; - memcached_st *memc= memcached_create(NULL); - char servername[]= "0.example.com"; - - servers= memcached_server_list_append(NULL, servername, 400, &rc); - - for (x= 0; x < 20; x++) + const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com" + memcached_st *memc= memcached_create_with_options(config_string, strlen(config_string); { - char buffer[SMALL_STRING_LEN]; - - snprintf(buffer, SMALL_STRING_LEN, "%u.example.com", 400+x); - servers= memcached_server_list_append(servers, buffer, 401, &rc); + ... } - rc= memcached_server_push(memc, servers); - memcached_server_free(servers); memcached_free(memc); -In the above code you create a \ ``memcached_st``\ object that you then feed in a -single host into. In the for loop you build a \ ``memcached_server_st``\ -pointer that you then later feed via memcached_server_push() into the -\ ``memcached_st``\ structure. - -You can reuse the \ ``memcached_server_st``\ object with multile \ ``memcached_st``\ -structures. +In the above code you create a \ ``memcached_st``\ object with three server by making use of :manpage:`memcached_create_with_options(3)`. ---------------------------- diff --git a/docs/man/libmemcached_examples.3 b/docs/man/libmemcached_examples.3 index 86867a28..d274724c 100644 --- a/docs/man/libmemcached_examples.3 +++ b/docs/man/libmemcached_examples.3 @@ -56,30 +56,16 @@ finished. .sp .nf .ft C -memcached_server_st *servers; -memcached_st *memc= memcached_create(NULL); -char servername[]= "0.example.com"; - -servers= memcached_server_list_append(NULL, servername, 400, &rc); - -for (x= 0; x < 20; x++) +const char *config_string= "\-\-SERVER=host10.example.com \-\-SERVER=host11.example.com \-\-SERVER=host10.example.com" +memcached_st *memc= memcached_create_with_options(config_string, strlen(config_string); { - char buffer[SMALL_STRING_LEN]; - - snprintf(buffer, SMALL_STRING_LEN, "%u.example.com", 400+x); - servers= memcached_server_list_append(servers, buffer, 401, &rc); + ... } -rc= memcached_server_push(memc, servers); -memcached_server_free(servers); memcached_free(memc); .ft P .fi .sp -In the above code you create a \fBmemcached_st\fP object that you then feed in a -single host into. In the for loop you build a \fBmemcached_server_st\fPpointer that you then later feed via memcached_server_push() into the -\fBmemcached_st\fP structure. -.sp -You can reuse the \fBmemcached_server_st\fP object with multile \fBmemcached_st\fPstructures. +In the above code you create a \fBmemcached_st\fP object with three server by making use of \fImemcached_create_with_options(3)\fP. .SH ADDING A VALUE TO THE SERVER .sp .nf diff --git a/docs/man/memcached_clone.3 b/docs/man/memcached_clone.3 index 81e28c97..798e6d8c 100644 --- a/docs/man/memcached_clone.3 +++ b/docs/man/memcached_clone.3 @@ -60,6 +60,8 @@ be used by other libmemcached(3) functions to communicate with the server. You should either pass a statically declared \fBmemcached_st\fP to memcached_create() or a NULL. If a NULL passed in then a structure is allocated for you. .sp +Please note, when you write new application use memcached_create_with_options() over memcached_create(). +.sp memcached_clone() is similar to memcached_create(3) but it copies the defaults and list of servers from the source \fBmemcached_st\fP. If you pass a null as the argument for the source to clone, it is the same as a call to memcached_create(). @@ -87,9 +89,6 @@ memcached_clone() returns a pointer to the memcached_st that was created .sp To find out more information please check: \fI\%https://launchpad.net/libmemcached\fP -.SH AUTHOR -.sp -Brian Aker, <\fI\%brian@tangent.org\fP> .SH SEE ALSO .sp \fImemcached(1)\fP \fIlibmemcached(3)\fP \fImemcached_strerror(3)\fP diff --git a/docs/man/memcached_create.3 b/docs/man/memcached_create.3 index 8aaf2efe..601175a6 100644 --- a/docs/man/memcached_create.3 +++ b/docs/man/memcached_create.3 @@ -60,6 +60,8 @@ be used by other libmemcached(3) functions to communicate with the server. You should either pass a statically declared \fBmemcached_st\fP to memcached_create() or a NULL. If a NULL passed in then a structure is allocated for you. .sp +Please note, when you write new application use memcached_create_with_options() over memcached_create(). +.sp memcached_clone() is similar to memcached_create(3) but it copies the defaults and list of servers from the source \fBmemcached_st\fP. If you pass a null as the argument for the source to clone, it is the same as a call to memcached_create(). @@ -87,9 +89,6 @@ memcached_clone() returns a pointer to the memcached_st that was created .sp To find out more information please check: \fI\%https://launchpad.net/libmemcached\fP -.SH AUTHOR -.sp -Brian Aker, <\fI\%brian@tangent.org\fP> .SH SEE ALSO .sp \fImemcached(1)\fP \fIlibmemcached(3)\fP \fImemcached_strerror(3)\fP diff --git a/docs/man/memcached_free.3 b/docs/man/memcached_free.3 index 3d5a32f7..ddf508af 100644 --- a/docs/man/memcached_free.3 +++ b/docs/man/memcached_free.3 @@ -60,6 +60,8 @@ be used by other libmemcached(3) functions to communicate with the server. You should either pass a statically declared \fBmemcached_st\fP to memcached_create() or a NULL. If a NULL passed in then a structure is allocated for you. .sp +Please note, when you write new application use memcached_create_with_options() over memcached_create(). +.sp memcached_clone() is similar to memcached_create(3) but it copies the defaults and list of servers from the source \fBmemcached_st\fP. If you pass a null as the argument for the source to clone, it is the same as a call to memcached_create(). @@ -87,9 +89,6 @@ memcached_clone() returns a pointer to the memcached_st that was created .sp To find out more information please check: \fI\%https://launchpad.net/libmemcached\fP -.SH AUTHOR -.sp -Brian Aker, <\fI\%brian@tangent.org\fP> .SH SEE ALSO .sp \fImemcached(1)\fP \fIlibmemcached(3)\fP \fImemcached_strerror(3)\fP diff --git a/docs/man/memcached_servers_reset.3 b/docs/man/memcached_servers_reset.3 index e92ca82b..42dde1fe 100644 --- a/docs/man/memcached_servers_reset.3 +++ b/docs/man/memcached_servers_reset.3 @@ -60,6 +60,8 @@ be used by other libmemcached(3) functions to communicate with the server. You should either pass a statically declared \fBmemcached_st\fP to memcached_create() or a NULL. If a NULL passed in then a structure is allocated for you. .sp +Please note, when you write new application use memcached_create_with_options() over memcached_create(). +.sp memcached_clone() is similar to memcached_create(3) but it copies the defaults and list of servers from the source \fBmemcached_st\fP. If you pass a null as the argument for the source to clone, it is the same as a call to memcached_create(). @@ -87,9 +89,6 @@ memcached_clone() returns a pointer to the memcached_st that was created .sp To find out more information please check: \fI\%https://launchpad.net/libmemcached\fP -.SH AUTHOR -.sp -Brian Aker, <\fI\%brian@tangent.org\fP> .SH SEE ALSO .sp \fImemcached(1)\fP \fIlibmemcached(3)\fP \fImemcached_strerror(3)\fP diff --git a/docs/memcached_create.rst b/docs/memcached_create.rst index 228dd570..ce692855 100644 --- a/docs/memcached_create.rst +++ b/docs/memcached_create.rst @@ -22,16 +22,18 @@ SYNOPSIS Compile and link with -lmemcached + ----------- DESCRIPTION ----------- - memcached_create() is used to create a \ ``memcached_st``\ structure that will then be used by other libmemcached(3) functions to communicate with the server. You should either pass a statically declared \ ``memcached_st``\ to memcached_create() or a NULL. If a NULL passed in then a structure is allocated for you. +Please note, when you write new application use memcached_create_with_options() over memcached_create(). + memcached_clone() is similar to memcached_create(3) but it copies the defaults and list of servers from the source \ ``memcached_st``\ . If you pass a null as the argument for the source to clone, it is the same as a call to memcached_create(). @@ -71,14 +73,6 @@ To find out more information please check: `https://launchpad.net/libmemcached `_ ------- -AUTHOR ------- - - -Brian Aker, - - -------- SEE ALSO -------- diff --git a/libmemcached/memcached.c b/libmemcached/memcached.c index f3f3c4a6..120c2087 100644 --- a/libmemcached/memcached.c +++ b/libmemcached/memcached.c @@ -213,19 +213,29 @@ memcached_st *memcached_create_with_options(const char *string, size_t length) memcached_st *self= memcached_create(NULL); if (! self) + { + errno= ENOMEM; return NULL; + } memcached_return_t rc; - if ((rc= memcached_parse_configuration(self, string, length)) != MEMCACHED_SUCCESS) + rc= memcached_parse_configuration(self, string, length); + + if (rc == MEMCACHED_SUCCESS && memcached_parse_filename(self)) { - return self; + rc= memcached_parse_configure_file(self, memcached_parse_filename(self), memcached_parse_filename_length(self)); } - if (memcached_parse_filename(self)) + + if (rc != MEMCACHED_SUCCESS) { - rc= memcached_parse_configure_file(self, memcached_parse_filename(self), memcached_parse_filename_length(self)); + memcached_free(self); + errno= EINVAL; + return NULL; } + errno= 0; + return self; } @@ -252,6 +262,9 @@ memcached_return_t memcached_reset(memcached_st *ptr) void memcached_servers_reset(memcached_st *ptr) { + if (! ptr) + return; + memcached_server_list_free(memcached_server_list(ptr)); memcached_server_list_set(ptr, NULL); @@ -266,6 +279,9 @@ void memcached_servers_reset(memcached_st *ptr) void memcached_reset_last_disconnected_server(memcached_st *ptr) { + if (! ptr) + return; + if (ptr->last_disconnected_server) { memcached_server_free(ptr->last_disconnected_server); @@ -275,6 +291,9 @@ void memcached_reset_last_disconnected_server(memcached_st *ptr) void memcached_free(memcached_st *ptr) { + if (! ptr) + return; + _free(ptr, true); } diff --git a/libmemcached/memcached.h b/libmemcached/memcached.h index adf55e21..fa291f93 100644 --- a/libmemcached/memcached.h +++ b/libmemcached/memcached.h @@ -178,7 +178,7 @@ LIBMEMCACHED_API memcached_st *memcached_create(memcached_st *ptr); LIBMEMCACHED_API -memcached_st *memcached_create_with_options(const char *string, size_t length); +memcached_st *memcached_create_with_options(const char *string, size_t string_length); LIBMEMCACHED_API void memcached_free(memcached_st *ptr); diff --git a/libmemcached/options.h b/libmemcached/options.h index 85fb8502..2785c122 100644 --- a/libmemcached/options.h +++ b/libmemcached/options.h @@ -44,12 +44,12 @@ extern "C" { LIBMEMCACHED_API memcached_return_t libmemcached_check_configuration(const char *option_string, size_t length, char *error_buffer, size_t error_buffer_size); -LIBMEMCACHED_API - memcached_return_t memcached_parse_configuration(memcached_st *ptr, const char *option_string, size_t length); - -LIBMEMCACHED_API +LIBMEMCACHED_LOCAL void memcached_set_configuration_file(memcached_st *self, const char *filename, size_t filename_length); +LIBMEMCACHED_LOCAL + memcached_return_t memcached_parse_configuration(memcached_st *ptr, const char *option_string, size_t length); + LIBMEMCACHED_LOCAL memcached_return_t memcached_parse_configure_file(memcached_st *ptr, const char *filename, size_t filename_length); diff --git a/tests/mem_functions.c b/tests/mem_functions.c index 95c33cbc..014c9bba 100644 --- a/tests/mem_functions.c +++ b/tests/mem_functions.c @@ -6217,7 +6217,6 @@ test_st parser_tests[] ={ {"hash", 0, (test_callback_fn)parser_hash_test }, {"libmemcached_check_configuration", 0, (test_callback_fn)libmemcached_check_configuration_test }, {"libmemcached_check_configuration_with_filename", 0, (test_callback_fn)libmemcached_check_configuration_with_filename_test }, - {"memcached_parse_configure_file", 0, (test_callback_fn)memcached_parse_configure_file_test }, {"number_options", 0, (test_callback_fn)parser_number_options_test }, {"randomly generated options", 0, (test_callback_fn)random_statement_build_test }, {"prefix_key", 0, (test_callback_fn)parser_key_prefix_test }, diff --git a/tests/parser.cc b/tests/parser.cc index b75ad41a..900e89a7 100644 --- a/tests/parser.cc +++ b/tests/parser.cc @@ -40,6 +40,7 @@ #include #include #include +#include #define BUILDING_LIBMEMCACHED #include @@ -118,30 +119,26 @@ static test_return_t __check_IO_MSG_WATERMARK(memcached_st *memc, const scanner_ return TEST_SUCCESS; } -static test_return_t __check_REMOVE_FAILED_SERVERS(memcached_st *memc, const scanner_string_st &value) +static test_return_t __check_REMOVE_FAILED_SERVERS(memcached_st *memc, const scanner_string_st &) { - (void)value; test_true(memcached_behavior_get(memc, MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS)); return TEST_SUCCESS; } -static test_return_t __check_NOREPLY(memcached_st *memc, const scanner_string_st &value) +static test_return_t __check_NOREPLY(memcached_st *memc, const scanner_string_st &) { - (void)value; test_true(memcached_behavior_get(memc, MEMCACHED_BEHAVIOR_NOREPLY)); return TEST_SUCCESS; } -static test_return_t __check_VERIFY_KEY(memcached_st *memc, const scanner_string_st &value) +static test_return_t __check_VERIFY_KEY(memcached_st *memc, const scanner_string_st &) { - (void)value; test_true(memcached_behavior_get(memc, MEMCACHED_BEHAVIOR_VERIFY_KEY)); return TEST_SUCCESS; } -static test_return_t __check_distribution_RANDOM(memcached_st *memc, const scanner_string_st &value) +static test_return_t __check_distribution_RANDOM(memcached_st *memc, const scanner_string_st &) { - (void)value; test_true(memcached_behavior_get(memc, MEMCACHED_BEHAVIOR_DISTRIBUTION) == MEMCACHED_DISTRIBUTION_RANDOM); return TEST_SUCCESS; } @@ -209,7 +206,7 @@ scanner_variable_t test_boolean_options[]= { scanner_variable_t prefix_key_strings[]= { { ARRAY, make_scanner_string("--PREFIX_KEY=foo"), make_scanner_string("foo"), __check_prefix_key }, { ARRAY, make_scanner_string("--PREFIX-KEY=\"foo\""), make_scanner_string("foo"), __check_prefix_key }, - { ARRAY, make_scanner_string("--PREFIX-KEY=\"This is a very long key\""), make_scanner_string("This is a very long key"), __check_prefix_key }, + { ARRAY, make_scanner_string("--PREFIX-KEY=\"This_is_a_very_long_key\""), make_scanner_string("This_is_a_very_long_key"), __check_prefix_key }, { NIL, scanner_string_null, scanner_string_null, NULL} }; @@ -238,36 +235,39 @@ scanner_variable_t hash_strings[]= { static test_return_t _test_option(scanner_variable_t *scanner, bool test_true= true) { (void)test_true; - memcached_st *memc; - memc= memcached_create(NULL); for (scanner_variable_t *ptr= scanner; ptr->type != NIL; ptr++) { - memcached_return_t rc; - rc= memcached_parse_configuration(memc, ptr->option.c_str, ptr->option.size); + memcached_st *memc; + memc= memcached_create_with_options(ptr->option.c_str, ptr->option.size); if (test_true) { - if (rc != MEMCACHED_SUCCESS) + if (not memc) { - memcached_error_print(memc); + char buffer[2048]; + memcached_return_t rc= libmemcached_check_configuration(ptr->option.c_str, ptr->option.size, buffer, sizeof(buffer)); + std::cerr << "About error for " << memcached_strerror(NULL, rc) << " : " << buffer << std::endl; } - test_true(rc == MEMCACHED_SUCCESS); + test_true(memc); if (ptr->check_func) { test_return_t test_rc= (*ptr->check_func)(memc, ptr->result); if (test_rc != TEST_SUCCESS) + { + memcached_free(memc); return test_rc; + } } + + memcached_free(memc); } else { - test_false_with(rc == MEMCACHED_SUCCESS, ptr->option.c_str); + test_false_with(memc, ptr->option.c_str); } - memcached_reset(memc); } - memcached_free(memc); return TEST_SUCCESS; } @@ -325,23 +325,6 @@ test_return_t parser_key_prefix_test(memcached_st*) #define SUPPORT_EXAMPLE_CNF "support/example.cnf" -test_return_t memcached_parse_configure_file_test(memcached_st*) -{ - if (access(SUPPORT_EXAMPLE_CNF, R_OK)) - return TEST_SKIPPED; - - memcached_st memc; - memcached_st *memc_ptr= memcached_create(&memc); - - test_true(memc_ptr); - - memcached_set_configuration_file(memc_ptr, memcached_string_with_size(SUPPORT_EXAMPLE_CNF)); - memcached_reset(memc_ptr); - memcached_free(memc_ptr); - - return TEST_SUCCESS; -} - test_return_t memcached_create_with_options_with_filename(memcached_st*) { if (access(SUPPORT_EXAMPLE_CNF, R_OK)) @@ -480,13 +463,31 @@ test_return_t random_statement_build_test(memcached_st*) random_options+= " "; } - memcached_return_t rc; memcached_st *memc_ptr= memcached_create(NULL); - rc= memcached_parse_configuration(memc_ptr, random_options.c_str(), random_options.size() -1); - if (rc == MEMCACHED_PARSE_ERROR) + memc_ptr= memcached_create_with_options(random_options.c_str(), random_options.size() -1); + if (not memc_ptr) { - std::cerr << std::endl << "Failed to parse(" << memcached_strerror(NULL, rc) << "): " << random_options << std::endl; - memcached_error_print(memc_ptr); + switch (errno) + { + case EINVAL: +#if 0 // Testing framework is not smart enough for this just yet. + { + // We will try to find the specific error + char buffer[2048]; + memcached_return_t rc= libmemcached_check_configuration(random_options.c_str(), random_options.size(), buffer, sizeof(buffer)); + test_true_got(rc != MEMCACHED_SUCCESS, "memcached_create_with_options() failed whiled libmemcached_check_configuration() was successful"); + std::cerr << "Error occured on " << random_options.c_str() << " : " << buffer << std::endl; + return TEST_FAILURE; + } +#endif + break; + case ENOMEM: + std::cerr << "Failed to allocate memory for memcached_create_with_options()" << std::endl; + return TEST_FAILURE; + default: + std::cerr << "Unknown error from memcached_create_with_options?!!" << std::endl; + return TEST_FAILURE; + } } memcached_free(memc_ptr); } diff --git a/tests/parser.h b/tests/parser.h index c12a7bdf..c50b3789 100644 --- a/tests/parser.h +++ b/tests/parser.h @@ -67,9 +67,6 @@ test_return_t parser_boolean_options_test(memcached_st*); LIBTEST_INTERNAL_API test_return_t parser_key_prefix_test(memcached_st*); -LIBTEST_INTERNAL_API -test_return_t memcached_parse_configure_file_test(memcached_st*); - LIBTEST_INTERNAL_API test_return_t libmemcached_check_configuration_test(memcached_st*); -- 2.30.2