From afe1867a80226a6751d87144e0e006dc6ebf26b7 Mon Sep 17 00:00:00 2001 From: Steven Dake Date: Sun, 21 May 2006 23:01:34 +0000 Subject: [PATCH] First take at doxygen support for openais APIs. git-svn-id: http://svn.fedorahosted.org/svn/corosync/trunk@1034 fd59a12c-fef9-0310-b244-a6a79926bd2f --- Doxyfile | 164 ++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 4 ++ include/cpg.h | 7 +++ include/evs.h | 13 +++- include/saAis.h | 4 ++ lib/ckpt.c | 9 +++ lib/clm.c | 101 +++++++++++++++++++++++++++++ lib/cpg.c | 9 +++ lib/evs.c | 24 +++++-- 9 files changed, 329 insertions(+), 6 deletions(-) create mode 100644 Doxyfile diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 00000000..752e913e --- /dev/null +++ b/Doxyfile @@ -0,0 +1,164 @@ +# Doxyfile 0.1 + +#--------------------------------------------------------------------------- +# General configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = openais +PROJECT_NUMBER = 0.75 +OUTPUT_DIRECTORY = doc/api +OUTPUT_LANGUAGE = English +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +INTERNAL_DOCS = NO +STRIP_CODE_COMMENTS = YES +CASE_SENSE_NAMES = YES +SHORT_NAMES = NO +HIDE_SCOPE_NAMES = NO +VERBATIM_HEADERS = YES +SHOW_INCLUDE_FILES = YES +JAVADOC_AUTOBRIEF = YES +INHERIT_DOCS = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +DISTRIBUTE_GROUP_DOC = NO +TAB_SIZE = 8 +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +ALIASES = +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +OPTIMIZE_OUTPUT_FOR_C = YES +SHOW_USED_FILES = YES +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = NO +WARN_FORMAT = +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = lib include +FILE_PATTERNS = *.c *.h +RECURSIVE = YES +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = NO +USE_PDFLATEX = NO +LATEX_BATCHMODE = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = YES +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = YES +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +SEARCH_INCLUDES = YES +INCLUDE_PATH = include +INCLUDE_FILE_PATTERNS = *.h +PREDEFINED = "OPENAIS_BEGIN_DECLS=" \ + "OPENAIS_END_DECLS=" \ + "DOXYGEN_SHOULD_SKIP_THIS" +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::addtions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +PERL_PATH = +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +HAVE_DOT = NO +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +TEMPLATE_RELATIONS = YES +HIDE_UNDOC_RELATIONS = YES +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +GRAPHICAL_HIERARCHY = YES +DOT_PATH = +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 640 +MAX_DOT_GRAPH_HEIGHT = 1024 +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::addtions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/Makefile b/Makefile index f411c5e7..9fa67c9d 100644 --- a/Makefile +++ b/Makefile @@ -75,6 +75,7 @@ clean: (cd lib; echo ==== `pwd` ===; $(MAKE) clean); (cd exec; echo ==== `pwd` ===; $(MAKE) clean); (cd test; echo ==== `pwd` ===; $(MAKE) clean); + rm -rf doc/api install: mkdir -p $(SBINDIR) @@ -126,3 +127,6 @@ install: install -m 644 man/*.3 $(MANDIR)/man3 install -m 644 man/*.8 $(MANDIR)/man8 /sbin/ldconfig + +doxygen: + doxygen diff --git a/include/cpg.h b/include/cpg.h index 3a958b83..8634dd6e 100644 --- a/include/cpg.h +++ b/include/cpg.h @@ -36,6 +36,11 @@ #include +/** + * @addtogroup cpg_openais + * + * @{ + */ typedef uint64_t cpg_handle_t; typedef enum { @@ -110,6 +115,8 @@ typedef struct { cpg_confchg_fn_t cpg_confchg_fn; } cpg_callbacks_t; +/** @} */ + /* * Create a new cpg connection */ diff --git a/include/evs.h b/include/evs.h index 01cb6846..11b11d2f 100644 --- a/include/evs.h +++ b/include/evs.h @@ -37,6 +37,15 @@ #include #include +/** + * @defgroup openais Other API services provided by openais + */ +/** + * @addtogroup evs_openais + * + * @{ + */ + typedef u_int64_t evs_handle_t; typedef enum { @@ -70,7 +79,7 @@ typedef enum { #define TOTEMIP_ADDRLEN (sizeof(struct in6_addr)) -/* These are the things that get passed around */ +/** These are the things that get passed around */ struct evs_address { unsigned int nodeid; unsigned short family; @@ -96,6 +105,8 @@ typedef struct { evs_confchg_fn_t evs_confchg_fn; } evs_callbacks_t; +/** @} */ + /* * Create a new evs connection */ diff --git a/include/saAis.h b/include/saAis.h index 90ab68b2..2e911459 100644 --- a/include/saAis.h +++ b/include/saAis.h @@ -35,6 +35,10 @@ #ifndef AIS_TYPES_H_DEFINED #define AIS_TYPES_H_DEFINED +/** + * @defgroup saf Service Availability Forum Application Interface Specification + */ + typedef enum { SA_FALSE = 0, SA_TRUE = 1 diff --git a/lib/ckpt.c b/lib/ckpt.c index 317f0cdf..a2732a4f 100644 --- a/lib/ckpt.c +++ b/lib/ckpt.c @@ -232,6 +232,13 @@ static void ckptInstanceFinalize (struct ckptInstance *ckptInstance) saHandleDestroy (&ckptHandleDatabase, ckptInstance->ckptHandle); } +/** + * @defgroup saCkpt SAF AIS Checkpoint API + * @ingroup saf + * + * @{ + */ + SaAisErrorT saCkptInitialize ( SaCkptHandleT *ckptHandle, @@ -1843,3 +1850,5 @@ error_put: return (SA_AIS_OK); } + +/** @} */ diff --git a/lib/clm.c b/lib/clm.c index 7294ee02..8660285a 100644 --- a/lib/clm.c +++ b/lib/clm.c @@ -91,6 +91,43 @@ void clmHandleInstanceDestructor (void *instance) } +/** + * @defgroup saClm SAF AIS Cluster Membership API + * @ingroup saf + * + * @{ + */ +/** + * This function initializes the Cluster Membership Service for the invoking + * process and registers the various callback functions. This function must + * be invoked prior to the invocation of any other Cluster Membership Service + * functionality. The handle clmHandle is returned as the reference to this + * association between the process and the Cluster Membership Service. The + * process uses this handle in subsequent communication with the Cluster + * Membership Service. + * + * @param clmHandle A pointer to the handle designating this particular + * initialization of the Cluster Membership Service that is to be + * returned by the Cluster Membership Service. + * @param clmCallbacks If clmCallbacks is set to NULL, no callback is + * registered; otherise, it is a pointer to an SaClmCallbacksT structure, + * containing the callback functions of the process that the Cluster + * Membership Service may invoke. Only non-NULL callback functions + * in this structure will be registered. + * @param version The version requested from the application is passed into + * this parameter and the version supported is returned. + * + * @returns SA_AIS_OK if the function completed successfully. + * @returns SA_AIS_ERR_LIBRARY if an unexpected problem occurred in + * the library. + * @returns SA_AIS_ERR_TRY_AGAIN if the service cannot be provided at this + * time. + * @returns SA_AIS_ERR_INVALID_PARAM if a parameter is not set correctly. + * @returns SA_AIS_ERR_NO_MEMORY if the Cluster Membership Service is out + * of memory and cannot provide the service. + * @returns SA_AIS_ERR_VERSION if the version parameter is not compatible with + * the version of the Cluster Membership Service implementation. + */ SaAisErrorT saClmInitialize ( SaClmHandleT *clmHandle, @@ -157,6 +194,28 @@ error_no_destroy: return (error); } +/** + * This function returns the operating system handle, selectionObject, + * assocated with the handle clmHandle. The invoking process can use this + * handle to detect pending callbacks, instead of repeatedly invoking + * saClmDispatch() for this purpose. + * + * In a POSIX environment, the operating system handle is a file descriptor + * that is used with the poll() or select() system calls to detect pending + * callbacks. + * + * The selectionObject returned by saClmSelectionObjectGet() is valid until + * saClmFinalize() is invoked on the same handle clmHandle. + * + * @param clmHandle The handle, obtained through the saClmInitialize function, + * designating this particular initialization of the Cluster Membership + * @param selectionObject A pointer to the operating system handle that the + * invoking process can use to detect pending callbacks. + * + * @returns SA_AIS_OK if the function completed successfully. + * @returns SA_AIS_ERR_BAD_HANDLE if the handle clmHandle is invalid, since it is + * ocrrupted, uninitialized, or has already been finalized. + */ SaAisErrorT saClmSelectionObjectGet ( SaClmHandleT clmHandle, @@ -180,6 +239,22 @@ saClmSelectionObjectGet ( return (SA_AIS_OK); } +/** + * This function invokes, in the context of the calling thread, pending callbacks for + * the handle clmhandle in a way that is specified by the dispatchFlags parameter. + * + * @param clmHandle The handle, obtained through the saClmInitialize() function, + * designating the particular initialization of the Cluster Membership Service. + * @param dispatchFlags Flags that specify the callback exection behavior of + * saClmDispatch, which have the values SA_DISPATCH_ONE, SA_DISPATCH_ALL, or + * SA_DISPATCH_BLOCKING. + * @returns SA_AIS_OK if the function completed successfully. + * @returns SA_AIS_ERR_TRY_AGAIN if the service cannot be provided at this time. The + * process may retry later. + * @returns SA_AIS_ERR_BAD_HANDLE if the handle clmHandle is invalid, since it is + * corrupted, uninitialized, or has already been finalized. + * @returns SA_AIS_ERR_INVALID_PARAM if the dispatchFlags parameter is valid. + */ SaAisErrorT saClmDispatch ( SaClmHandleT clmHandle, @@ -355,6 +430,30 @@ error_put: return (error); } + +/** + * The saClmFinalize function closes the assocation, represented by the clmHandle + * parameter, between the invoking process and the Cluster Membership Service. The + * process must have invoked saClmInitialize before it invokes this function. A + * process must invoke this function once for each handle it acquired by invoking + * saClmInitialize(). + * + * If the saClmFinalize() function returns successfully, the saClmFinalize() function + * releases all resources acquired when saClmInitialize(0 was called. Moreover, it + * stops any tracking associated with the particular handle. Furthermore, it cancels + * all pending callbacks related to the particular handle. Note that because the + * callback invocation is asynchronous, it is still possible that some callback calls + * are processed after this call returns successfully. + * + * After saClmFinalize() is invoked, the selection object is no longer valid. + * + * @param clmHandle The handle, obtained through the saClmInitialize() function, + * designating this particular initialization of the Cluster Membership Service. + * + * @returns SA_AIS_OK if the function completed successfully. + * @returns SA_AIS_ERR_BAD_HANDLE if the handle clmHandle is invalid, since it is + * corrupted, uninitialized, or has already been finalized. + */ SaAisErrorT saClmFinalize ( SaClmHandleT clmHandle) @@ -624,3 +723,5 @@ error_exit: return (error); } + +/** @} */ diff --git a/lib/cpg.c b/lib/cpg.c index 6d3bc974..17aa62b1 100644 --- a/lib/cpg.c +++ b/lib/cpg.c @@ -76,6 +76,13 @@ static void cpg_instance_destructor (void *instance) } +/** + * @defgroup cpg_openais The closed process group API + * @ingroup openais + * + * @{ + */ + cpg_error_t cpg_initialize ( cpg_handle_t *handle, cpg_callbacks_t *callbacks) @@ -550,3 +557,5 @@ error_exit: return (error); } + +/** @} */ diff --git a/lib/evs.c b/lib/evs.c index 27425652..f2277327 100644 --- a/lib/evs.c +++ b/lib/evs.c @@ -59,6 +59,11 @@ struct evs_inst { pthread_mutex_t dispatch_mutex; }; +struct res_overlay { + struct res_header header; + char data[512000]; +}; + static void evs_instance_destructor (void *instance); static struct saHandleDatabase evs_handle_t_db = { @@ -76,6 +81,18 @@ static void evs_instance_destructor (void *instance) } +/** + * @defgroup evs_openais The extended virtual synchrony passthrough API + * @ingroup openais + * + * @{ + */ +/** + * test + * @param handle The handle of evs initialize + * @param callbacks The callbacks for evs_initialize + * @returns EVS_OK + */ evs_error_t evs_initialize ( evs_handle_t *handle, evs_callbacks_t *callbacks) @@ -181,11 +198,6 @@ evs_error_t evs_fd_get ( return (SA_AIS_OK); } -struct res_overlay { - struct res_header header; - char data[512000]; -}; - evs_error_t evs_dispatch ( evs_handle_t handle, evs_dispatch_t dispatch_types) @@ -591,3 +603,5 @@ error_exit: return (error); } + +/** @} */