Index: trunk/vm/include/component_manager.h
===================================================================
--- trunk/vm/include/component_manager.h (revision 527072)
+++ trunk/vm/include/component_manager.h (working copy)
@@ -1,4 +1,4 @@
-/*
+/**
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
@@ -25,12 +25,12 @@
#endif
/**
- * If no component manager exist, initializes a component manager.
- * Otherwise, increases a component manager reference count.
+ * Initializes a component manager if it does not exist.
+ * Otherwise, increases a component-manager reference count.
*
* This function is safe to call from multiple threads.
*
- * @param[out] p_cm - on return, points to a component manager
+ * @param[out] p_cm - on return, points to a component-manager
* interface handle
*
* @return APR_SUCCESS if successful, or a non-zero error code.
@@ -38,7 +38,7 @@
int CmAcquire(OpenComponentManagerHandle* p_cm);
/**
- * Decrement a reference counter and destroy a component manager if it
+ * Decrements a reference counter and destroys a component manager if it
* becomes zero. The caller should ensure no cached handles will be used.
*
* This function is safe to call from multiple threads.
@@ -48,9 +48,9 @@
int CmRelease();
/**
- * Register a buitin component in a component manager.
+ * Registers a built-in component in a component manager.
*
- * @param init_func - initializer function which provides a default
+ * @param init_func - the initializer function providing a default
* and private interfaces for the component
*
* This function is safe to call from multiple threads.
@@ -60,15 +60,16 @@
int CmAddComponent(OpenComponentInitializer init_func);
/**
- * Load a dynamic library if not loaded, and register
- * the component with a given initializer function
- * in a component manager.
+ * Loads a dynamic library if it was not loaded, and registers
+ * the component with the given initializer function in a component manager.
*
* This function is safe to call from multiple threads.
*
- * @param path - path to DLL which contains a component
- * @param initializer_function_name - a name of a function of OpenComponentInitializer
- * type that registers a component in a component manager
+ * @param path - the path to DLL, which contains a component
+ * @param initializer_function_name - the function name of the
+ * OpenComponentInitializer type
+ * that registers a component in a component
+ * manager
*
* @return APR_SUCCESS if successful, or a non-zero error code.
*/
@@ -76,10 +77,10 @@
const char* initializer_function_name);
/**
- * Deallocate all instances of a given component, unregister a component in a
- * component manager, and free all component resources using
- * Free function. If the component is loaded from a dynamic
- * library and no components are using the library, then unload
+ * De-allocates all instances of the given component, unregisters a component in a
+ * component manager, and frees all component resources using the
+ * Free function. If the component is loaded from a dynamic
+ * library and no components are using the library, then unloads
* the dynamic library.
*
* This function is safe to call from multiple threads.
Index: trunk/vm/include/open/compmgr.h
===================================================================
--- trunk/vm/include/open/compmgr.h (revision 527072)
+++ trunk/vm/include/open/compmgr.h (working copy)
@@ -1,10 +1,10 @@
-/*
+/**
* Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
+ * contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -14,18 +14,18 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
+
+/**
* @author Intel, Alexei Fedotov
* @version $Revision: 1.1.2.2.4.3 $
*/
/**
* @file
- *
- * The file contains description of public component manager handles
- * and interfaces for initialization and dynamic linking of VM components.
+ * Description of public component-manager handles and interfaces for
+ * initialization and dynamic linking of VM components.
*/
-
+
#ifndef _OPEN_COMPMGR_H
#define _OPEN_COMPMGR_H
@@ -37,25 +37,25 @@
#endif
/**
- * The _OpenInterface structure represents
- * a virtual table of interface functions.
+ * The _OpenInterface structure represents a virtual table of
+ * interface functions.
+ *
+ * A real interface can contain more function pointers.
+ *
+ * void* func2; + * void* func3; + **/ struct _OpenInterface { void* func1; - /* - * A real interface can contain more - * function pointers. - * - * void* func2; - * void* func3; - */ + }; /** * @name Handles - * Handles are opaque for an interface user. The user - * operates with handles by means of interface functions. + * Handles are opaque for an interface user. The user operates with handles + * by means of interface functions. */ /** @@ -65,79 +65,76 @@ typedef const struct _OpenInterface* OpenInterfaceHandle; /** - * Default component interface. Each component must - * provide implementation of the functions from this - * interface. + * The default component interface. Each component must provide implementation + * of the functions from this interface. */ struct _OpenComponent { - /** - * Returns a component name. - */ +/** Returns a component name.*/ const char* (*GetName) (); - /** - * Returns a component version which is numbers separated with dots. - * Implementors must check a major version number for compatibility. - */ +/** + * Returns a component version where numbers are separated with dots. + * Implementors must check the major version number for compatibility. + */ const char* (*GetVersion) (); - /** - * Returns human-readable description of the component. - */ +/** Returns the human-readable description of the component.*/ const char* (*GetDescription) (); - /** - * Returns the human-readable vendor string, e. g., - * name of the organization which provides this component. - */ +/** + * Returns the human-readable vendor string, for example, the name of the + * organization providing this component. + */ const char* (*GetVendor) (); - /** - * Queries optional properties. - * @param key property name - * @return a string, true/false for boolean properties - */ +/** + * Queries optional properties. + * + * @param key - the property name + * @return A string,
TRUE/FALSE for boolean properties.
+ */
const char* (*GetProperty) (const char* key);
- /**
- * Exposes a NULL terminated list of component-specific
- * interface names for the given component.
- *
- * This default component interface is not included.
- * @return a pointer to an internal component manager structure,
- * which should not be modified or freed.
- */
+/**
+ * Exposes a NULL terminated list of component-specific interface
+ * names for the given component.
+ *
+ * This default component interface is not included.
+ *
+ * @return A pointer to an internal component-manager structure, which should
+ * not be modified or freed.
+ */
const char** (*ListInterfaceNames) ();
- /**
- * Exposes a component interface.
- * @param[out] p_intf on return, points to an interface handle
- * @param intf_name an interface name
- * @return APR_SUCCESS if successful, otherwise a non-zero error code
- */
+/**
+ * Exposes a component interface.
+ *
+ * @param[out] p_intf - on return, points to an interface handle
+ * @param intf_name - an interface name
+ * @return APR_SUCCESS if successful, otherwise a non-zero error code.
+ */
int (*GetInterface) (OpenInterfaceHandle* p_intf,
const char* intf_name);
- /**
- * The call to this function frees all component resources.
- * @return APR_SUCCESS if successful, otherwise a non-zero error code
- */
+/**
+ * The call to this function frees all component resources.
+ *
+ * @return APR_SUCCESS if successful, otherwise a non-zero error code.
+ */
int (*Free) ();
};
/**
* @ingroup Handles
- * The handle of the open component.
+ * The open component handle.
*/
typedef const struct _OpenComponent* OpenComponentHandle;
-/**
- * The generic component instance.
- */
+/** The generic component instance.*/
struct _OpenInstance
{
OpenComponentHandle intf;
};
/**
* @ingroup Handles
- * The handle of the open instance.
+ * The open instance handle.
*/
typedef const struct _OpenInstance* OpenInstanceHandle;
@@ -146,24 +143,26 @@
* and dispose instances.
*/
struct _OpenInstanceAllocator {
- /**
- * The component provides a constructor-like method for instance
- * initialization which is called by component manager when a
- * new instance is created.
- *
- * @param[out] p_instance on return, points to handle of a new instance
- * @param pool created by a component manager for a lifetime of
- * the instance, the component could use the pool for allocation
- * @return APR_SUCCESS if successful, otherwise a non-zero error code
- */
+/**
+ * The component provides a constructor-like method for instance
+ * initialization which is called by a component manager when a
+ * new instance is created.
+ *
+ * @param[out] p_instance - on return, points to the new instance handle
+ * @param pool - the pool created by a component manager for a
+ * lifetime of the instance, the component can use
+ * the pool for allocation
+ * @return APR_SUCCESS if successful, otherwise a non-zero error code.
+ */
int (*CreateInstance) (OpenInstanceHandle* p_instance,
apr_pool_t* pool);
- /**
- * Free memory and other resources for a given instance.
- * @param instance a handle of an instance to free
- * @return APR_SUCCESS if successful, otherwise a non-zero error code
- */
+/**
+ * Free memory and other resources for the given instance.
+ *
+ * @param instance - a handle of an instance to free
+ * @return APR_SUCCESS if successful, otherwise a non-zero error code.
+ */
int (*FreeInstance) (OpenInstanceHandle instance);
};
/**
@@ -173,7 +172,7 @@
typedef const struct _OpenInstanceAllocator* OpenInstanceAllocatorHandle;
/**
- * The virtual table which contains public component manager
+ * The virtual table containing the public component-manager
* interface. The interface allows accessing components by name
* and operating with component instances.
*
@@ -182,50 +181,53 @@
struct _OpenComponentManager
{
- /**
- * Get a default interface of a registered component by name.
- * @param[out] p_component on return, points to
- * a handle of default component interface
- * @param name a component name
- * @return APR_SUCCESS if successful, otherwise a non-zero error code
- */
+/**
+ * Gets a default interface of a registered component by name.
+ *
+ * @param[out] p_component - on return, points to a handle of default component
+ * interface
+ * @param name - the component name
+ * @return APR_SUCCESS if successful, otherwise a non-zero error code.
+ */
int (*GetComponent) (OpenComponentHandle* p_component,
const char* name);
- /**
- * Create a new component instance and register it in
- * a component manager.
- * @param[out] p_instance on return, points to a handle of a newly
- * created instance
- * @param name a name of interface
- * @return APR_SUCCESS if successful, otherwise a non-zero error code
- */
+/**
+ * Creates a new component instance and registers it in a component manager.
+ *
+ * @param[out] p_instance - on return, points to a handle of a newly
+ * created instance
+ * @param name - the interface name
+ * @return APR_SUCCESS if successful, otherwise a non-zero error code.
+ */
int (*CreateInstance) (OpenInstanceHandle* p_instance,
const char* name);
- /**
- * Unregister the instance in a component manager,
- * free memory and other resources held by the instance.
- * @param instance a handle to the instance to Free
- * @return APR_SUCCESS if successful, otherwise a non-zero error code
- */
+/**
+ * Unregisters the instance in a component manager, free memory and other
+ * resources held by the instance.
+ *
+ * @param instance - a handle to the instance to Free
+ * @return APR_SUCCESS if successful, otherwise a non-zero error code.
+ */
int (*FreeInstance) (OpenInstanceHandle instance);
};
/**
* @ingroup Handles
- * The handle of the component manager interface.
+ * The handle of the component-manager interface.
*/
typedef const struct _OpenComponentManager* OpenComponentManagerHandle;
/**
* The generic component initialization function type.
- * @param[out] p_component on return, points to a handle of a default
- * component interface
- * @param[out] p_allocator on return, points to a handle of a private
- * instance allocation interface
- * @param pool a memory pool with the component lifetime
- * @return APR_SUCCESS if successful, otherwise a non-zero error code
+ *
+ * @param[out] p_component - on return, points to a handle of a default
+ * component interface
+ * @param[out] p_allocator - on return, points to a handle of a private
+ * instance allocation interface
+ * @param pool - the memory pool with the component lifetime
+ * @return APR_SUCCESS if successful, otherwise a non-zero error code.
*/
typedef int
(*OpenComponentInitializer) (OpenComponentHandle* p_component,