List:Commits« Previous MessageNext Message »
From:Marc Alff Date:April 4 2011 2:34pm
Subject:bzr commit into mysql-trunk branch (marc.alff:3325)
View as plain text  
#At file:///Users/malff/BZR_TREE/mysql-trunk-cleanup/ based on revid:luis.soares@stripped

 3325 Marc Alff	2011-04-04
      Improved doxygen documentation for the performance schema.

    modified:
      storage/perfschema/ha_perfschema.h
      storage/perfschema/pfs.h
      storage/perfschema/pfs_atomic.h
      storage/perfschema/pfs_column_types.h
      storage/perfschema/pfs_column_values.h
      storage/perfschema/pfs_con_slice.h
      storage/perfschema/pfs_defaults.h
      storage/perfschema/pfs_engine_table.h
      storage/perfschema/pfs_events_statements.h
      storage/perfschema/pfs_global.h
      storage/perfschema/pfs_instr.h
      storage/perfschema/pfs_server.h
      storage/perfschema/pfs_setup_actor.cc
      storage/perfschema/pfs_timer.h
=== modified file 'storage/perfschema/ha_perfschema.h'
--- a/storage/perfschema/ha_perfschema.h	2011-03-22 11:44:40 +0000
+++ b/storage/perfschema/ha_perfschema.h	2011-04-04 14:34:42 +0000
@@ -28,12 +28,18 @@
 */
 struct PFS_engine_table_share;
 class PFS_engine_table;
+/** Name of the performance schema engine. */
 extern const char *pfs_engine_name;
 
 /** A handler for a PERFORMANCE_SCHEMA table. */
 class ha_perfschema : public handler
 {
 public:
+  /**
+    Create a new performance schema table handle on a table.
+    @param hton storage engine handler singleton
+    @param share table share
+  */
   ha_perfschema(handlerton *hton, TABLE_SHARE *share);
 
   ~ha_perfschema();
@@ -97,26 +103,72 @@ public:
   double scan_time(void)
   { return 1.0; }
 
+  /**
+    Open a performance schema table.
+    @param name the table to open
+    @param mode unused
+    @param test_if_locked unused
+    @return 0 on success
+  */
   int open(const char *name, int mode, uint test_if_locked);
 
+  /**
+    Close a table handle.
+    @sa open.
+  */
   int close(void);
 
+  /**
+    Write a row.
+    @param buf the row to write
+    @return 0 on success
+  */
   int write_row(uchar *buf);
 
   void use_hidden_primary_key();
 
+  /**
+    Update a row.
+    @param old_data the row old values
+    @param new_data the row new values
+    @return 0 on success
+  */
   int update_row(const uchar *old_data, uchar *new_data);
 
+  /**
+    Delete a row.
+    @param buf the row to delete
+    @return 0 on success
+  */
   int delete_row(const uchar *buf);
 
   int rnd_init(bool scan);
 
+  /**
+    Scan end.
+    @sa rnd_init.
+  */
   int rnd_end(void);
 
+  /**
+    Iterator, fetch the next row.
+    @param[out] buf the row fetched.
+    @return 0 on success
+  */
   int rnd_next(uchar *buf);
 
+  /**
+    Iterator, fetch the row at a given position.
+    @param[out] buf the row fetched.
+    @param pos the row position
+    @return 0 on success
+  */
   int rnd_pos(uchar *buf, uchar *pos);
 
+  /**
+    Read the row current position.
+    @param record the current row
+  */
   void position(const uchar *record);
 
   int info(uint);

=== modified file 'storage/perfschema/pfs.h'
--- a/storage/perfschema/pfs.h	2010-07-16 01:28:30 +0000
+++ b/storage/perfschema/pfs.h	2011-04-04 14:34:42 +0000
@@ -27,8 +27,14 @@
 #include <my_pthread.h>
 #include <mysql/psi/psi.h>
 
+/**
+  Entry point to the performance schema implementation.
+  This singleton is used to discover the performance schema services.
+*/
 extern struct PSI_bootstrap PFS_bootstrap;
+/** Performance schema Thread Local Storage key.  */
 extern pthread_key(PFS_thread*, THR_PFS);
+/** True when @c THR_PFS is initialized. */
 extern bool THR_PFS_initialized;
 
 #endif

=== modified file 'storage/perfschema/pfs_atomic.h'
--- a/storage/perfschema/pfs_atomic.h	2010-07-16 01:28:30 +0000
+++ b/storage/perfschema/pfs_atomic.h	2011-04-04 14:34:42 +0000
@@ -27,7 +27,9 @@
 class PFS_atomic
 {
 public:
+  /** Initialise the PFS_atomic component. */
   static void init();
+  /** Cleanup the PFS_atomic component. */
   static void cleanup();
 
   /** Atomic load. */
@@ -112,6 +114,10 @@ public:
 private:
   static my_atomic_rwlock_t m_rwlock_array[256];
 
+  /**
+    Helper used only with non native atomic implementations.
+    @sa MY_ATOMIC_MODE_RWLOCKS
+  */
   static inline my_atomic_rwlock_t *get_rwlock(volatile void *ptr)
   {
     /*
@@ -123,21 +129,37 @@ private:
     return result;
   }
 
+  /**
+    Helper used only with non native atomic implementations.
+    @sa MY_ATOMIC_MODE_RWLOCKS
+  */
   static inline void rdlock(volatile void *ptr)
   {
     my_atomic_rwlock_rdlock(get_rwlock(ptr));
   }
 
+  /**
+    Helper used only with non native atomic implementations.
+    @sa MY_ATOMIC_MODE_RWLOCKS
+  */
   static inline void wrlock(volatile void *ptr)
   {
     my_atomic_rwlock_wrlock(get_rwlock(ptr));
   }
 
+  /**
+    Helper used only with non native atomic implementations.
+    @sa MY_ATOMIC_MODE_RWLOCKS
+  */
   static inline void rdunlock(volatile void *ptr)
   {
     my_atomic_rwlock_rdunlock(get_rwlock(ptr));
   }
 
+  /**
+    Helper used only with non native atomic implementations.
+    @sa MY_ATOMIC_MODE_RWLOCKS
+  */
   static inline void wrunlock(volatile void *ptr)
   {
     my_atomic_rwlock_wrunlock(get_rwlock(ptr));

=== modified file 'storage/perfschema/pfs_column_types.h'
--- a/storage/perfschema/pfs_column_types.h	2011-02-14 14:23:55 +0000
+++ b/storage/perfschema/pfs_column_types.h	2011-04-04 14:34:42 +0000
@@ -68,8 +68,11 @@ enum enum_timer_name
   TIMER_NAME_TICK= 5
 };
 
+/** Integer, first value of @sa enum_timer_name. */
 #define FIRST_TIMER_NAME (static_cast<int> (TIMER_NAME_CYCLE))
+/** Integer, last value of @sa enum_timer_name. */
 #define LAST_TIMER_NAME (static_cast<int> (TIMER_NAME_TICK))
+/** Integer, number of values of @sa enum_timer_name. */
 #define COUNT_TIMER_NAME (LAST_TIMER_NAME - FIRST_TIMER_NAME + 1)
 
 /**
@@ -146,17 +149,26 @@ enum enum_operation_type
   OPERATION_TYPE_TL_READ_EXTERNAL= 39,
   OPERATION_TYPE_TL_WRITE_EXTERNAL= 40
 };
+/** Integer, first value of @sa enum_operation_type. */
 #define FIRST_OPERATION_TYPE (static_cast<int> (OPERATION_TYPE_LOCK))
+/** Integer, last value of @sa enum_operation_type. */
 #define LAST_OPERATION_TYPE (static_cast<int> (OPERATION_TYPE_TL_WRITE_EXTERNAL))
+/** Integer, number of values of @sa enum_operation_type. */
 #define COUNT_OPERATION_TYPE (LAST_OPERATION_TYPE - FIRST_OPERATION_TYPE + 1)
 
+/**
+  Enum values for the various OBJECT_TYPE columns.
+*/
 enum enum_object_type
 {
   OBJECT_TYPE_TABLE= 1,
   OBJECT_TYPE_TEMPORARY_TABLE= 2
 };
+/** Integer, first value of @sa enum_object_type. */
 #define FIRST_OBJECT_TYPE (static_cast<int> (OBJECT_TYPE_TABLE))
+/** Integer, last value of @sa enum_object_type. */
 #define LAST_OBJECT_TYPE (static_cast<int> (OBJECT_TYPE_TEMPORARY_TABLE))
+/** Integer, number of values of @sa enum_object_type. */
 #define COUNT_OBJECT_TYPE (LAST_OBJECT_TYPE - FIRST_OBJECT_TYPE + 1)
 
 /**
@@ -173,8 +185,11 @@ enum enum_event_type
   EVENT_TYPE_WAIT= 3
 };
 
+/** Integer, first value of @sa enum_event_type. */
 #define FIRST_EVENT_TYPE (static_cast<int> (EVENT_TYPE_STATEMENT))
+/** Integer, last value of @sa enum_event_type. */
 #define LAST_EVENT_TYPE (static_cast<int> (EVENT_TYPE_WAIT))
+/** Integer, number of values of @sa enum_event_type. */
 #define COUNT_EVENT_TYPE (LAST_EVENT_TYPE - FIRST_EVENT_TYPE + 1)
 
 #endif

=== modified file 'storage/perfschema/pfs_column_values.h'
--- a/storage/perfschema/pfs_column_values.h	2011-02-14 14:23:55 +0000
+++ b/storage/perfschema/pfs_column_values.h	2011-04-04 14:34:42 +0000
@@ -24,14 +24,22 @@
   performance schema tables (declarations).
 */
 
+/** String, "PERFORMANCE_SCHEMA". */
 extern LEX_STRING PERFORMANCE_SCHEMA_str;
 
+/** String prefix for all mutex instruments. */
 extern LEX_STRING mutex_instrument_prefix;
+/** String prefix for all rwlock instruments. */
 extern LEX_STRING rwlock_instrument_prefix;
+/** String prefix for all cond instruments. */
 extern LEX_STRING cond_instrument_prefix;
+/** String prefix for all thread instruments. */
 extern LEX_STRING thread_instrument_prefix;
+/** String prefix for all file instruments. */
 extern LEX_STRING file_instrument_prefix;
+/** String prefix for all stage instruments. */
 extern LEX_STRING stage_instrument_prefix;
+/** String prefix for all statement instruments. */
 extern LEX_STRING statement_instrument_prefix;
 
 #endif

=== modified file 'storage/perfschema/pfs_con_slice.h'
--- a/storage/perfschema/pfs_con_slice.h	2011-02-14 14:23:55 +0000
+++ b/storage/perfschema/pfs_con_slice.h	2011-04-04 14:34:42 +0000
@@ -33,12 +33,32 @@ struct PFS_statement_stat;
   @{
 */
 
+/**
+  A connection slice, an arbitrary grouping of several connections.
+  This structure holds statistics for grouping of connections.
+*/
 struct PFS_connection_slice
 {
+  /**
+    Allocate memory for waits statistics.
+    @param sizing the number of wait classes.
+    @return wait statistics for this slice.
+  */
   static PFS_single_stat *alloc_waits_slice(uint sizing);
+  /**
+    Allocate memory for stages statistics.
+    @param sizing the number of stage classes.
+    @return stage statistics for this slice.
+  */
   static PFS_stage_stat *alloc_stages_slice(uint sizing);
+  /**
+    Allocate memory for statement statistics.
+    @param sizing the number of statement classes.
+    @return statement statistics for this slice.
+  */
   static PFS_statement_stat *alloc_statements_slice(uint sizing);
 
+  /** Reset all statistics. */
   inline void reset_stats()
   {
     reset_waits_stats();
@@ -46,8 +66,11 @@ struct PFS_connection_slice
     reset_statements_stats();
   }
 
+  /** Reset all wait statistics. */
   void reset_waits_stats();
+  /** Reset all stages statistics. */
   void reset_stages_stats();
+  /** Reset all statements statistics. */
   void reset_statements_stats();
 
   /**

=== modified file 'storage/perfschema/pfs_defaults.h'
--- a/storage/perfschema/pfs_defaults.h	2010-07-02 16:15:37 +0000
+++ b/storage/perfschema/pfs_defaults.h	2011-04-04 14:34:42 +0000
@@ -21,6 +21,12 @@
   Default setup (declarations).
 */
 
+/**
+  Configure the performance schema setup tables with default content.
+  The tables populated are:
+  - SETUP_ACTORS
+  - SETUP_OBJECTS
+*/
 void install_default_setup(PSI_bootstrap *boot);
 
 #endif

=== modified file 'storage/perfschema/pfs_engine_table.h'
--- a/storage/perfschema/pfs_engine_table.h	2011-02-04 11:55:17 +0000
+++ b/storage/perfschema/pfs_engine_table.h	2011-04-04 14:34:42 +0000
@@ -46,6 +46,13 @@ public:
   int update_row(TABLE *table, const unsigned char *old_buf,
                  unsigned char *new_buf, Field **fields);
 
+  /**
+    Delete a row from this table.
+    @param table Table handle
+    @param buf the row buffer to delete
+    @param fields Table fields
+    @return 0 on success
+  */
   int delete_row(TABLE *table, const unsigned char *buf, Field **fields);
 
   /** Fetch the next row in this cursor. */
@@ -58,21 +65,71 @@ public:
 
   void get_position(void *ref);
   void set_position(const void *ref);
+  /** Reset the cursor position to the beginning of the table. */
   virtual void reset_position(void)= 0;
 
   /** Destructor. */
   virtual ~PFS_engine_table()
   {}
 
+  /**
+    Helper, assign a value to a ulong field.
+    @param f the field to set
+    @param value the value to assign
+  */
   static void set_field_ulong(Field *f, ulong value);
+  /**
+    Helper, assign a value to a ulonglong field.
+    @param f the field to set
+    @param value the value to assign
+  */
   static void set_field_ulonglong(Field *f, ulonglong value);
+  /**
+    Helper, assign a value to a char utf8 field.
+    @param f the field to set
+    @param str the string to assign
+    @param len the length of the string to assign
+  */
   static void set_field_char_utf8(Field *f, const char *str, uint len);
+  /**
+    Helper, assign a value to a varchar utf8 field.
+    @param f the field to set
+    @param str the string to assign
+    @param len the length of the string to assign
+  */
   static void set_field_varchar_utf8(Field *f, const char *str, uint len);
+  /**
+    Helper, assign a value to a longtext utf8 field.
+    @param f the field to set
+    @param str the string to assign
+    @param len the length of the string to assign
+  */
   static void set_field_longtext_utf8(Field *f, const char *str, uint len);
+  /**
+    Helper, assign a value to an enum field.
+    @param f the field to set
+    @param value the value to assign
+  */
   static void set_field_enum(Field *f, ulonglong value);
-
+  /**
+    Helper, read a value from an enum field.
+    @param f the field to read
+    @return the field value
+  */
   static ulonglong get_field_enum(Field *f);
+  /**
+    Helper, read a value from a char utf8 field.
+    @param f the field to read
+    @param[out] val the field value
+    @return the field value
+  */
   static String *get_field_char_utf8(Field *f, String *val);
+  /**
+    Helper, read a value from a varchar utf8 field.
+    @param f the field to read
+    @param[out] val the field value
+    @return the field value
+  */
   static String *get_field_varchar_utf8(Field *f, String *val);
 
 protected:
@@ -274,16 +331,29 @@ struct PFS_simple_index
   /** Current row index. */
   uint m_index;
 
+  /**
+    Constructor.
+    @param index the index initial value.
+  */
   PFS_simple_index(uint index)
     : m_index(index)
   {}
 
+  /**
+    Set this index at a given position.
+    @param other a position
+  */
   void set_at(const struct PFS_simple_index *other)
   { m_index= other->m_index; }
 
+  /**
+    Set this index after a given position.
+    @param other a position
+  */
   void set_after(const struct PFS_simple_index *other)
   { m_index= other->m_index + 1; }
 
+  /** Set this index to the next record. */
   void next(void)
   { m_index++; }
 };
@@ -296,16 +366,29 @@ struct PFS_double_index
   /** Current index within index_1. */
   uint m_index_2;
 
+  /**
+    Constructor.
+    @param index_1 the first index initial value.
+    @param index_2 the second index initial value.
+  */
   PFS_double_index(uint index_1, uint index_2)
     : m_index_1(index_1), m_index_2(index_2)
   {}
 
+  /**
+    Set this index at a given position.
+    @param other a position
+  */
   void set_at(const struct PFS_double_index *other)
   {
     m_index_1= other->m_index_1;
     m_index_2= other->m_index_2;
   }
 
+  /**
+    Set this index after a given position.
+    @param other a position
+  */
   void set_after(const struct PFS_double_index *other)
   {
     m_index_1= other->m_index_1;
@@ -323,10 +406,20 @@ struct PFS_triple_index
   /** Current index within index_2. */
   uint m_index_3;
 
+  /**
+    Constructor.
+    @param index_1 the first index initial value.
+    @param index_2 the second index initial value.
+    @param index_3 the third index initial value.
+  */
   PFS_triple_index(uint index_1, uint index_2, uint index_3)
     : m_index_1(index_1), m_index_2(index_2), m_index_3(index_3)
   {}
 
+  /**
+    Set this index at a given position.
+    @param other a position
+  */
   void set_at(const struct PFS_triple_index *other)
   {
     m_index_1= other->m_index_1;
@@ -334,6 +427,10 @@ struct PFS_triple_index
     m_index_3= other->m_index_3;
   }
 
+  /**
+    Set this index after a given position.
+    @param other a position
+  */
   void set_after(const struct PFS_triple_index *other)
   {
     m_index_1= other->m_index_1;

=== modified file 'storage/perfschema/pfs_events_statements.h'
--- a/storage/perfschema/pfs_events_statements.h	2011-02-14 14:23:55 +0000
+++ b/storage/perfschema/pfs_events_statements.h	2011-04-04 14:34:42 +0000
@@ -41,32 +41,51 @@ struct PFS_events_statements : public PF
   /** Length of @ m_info. */
   uint m_sqltext_length;
 
-  /* Lock */
+  /** Locked time. */
   ulonglong m_lock_time;
 
-  /* Diagnostics area */
+  /** Diagnostics area, message text. */
   char m_message_text[MYSQL_ERRMSG_SIZE+1];
+  /** Diagnostics area, error number. */
   uint m_sql_errno;
+  /** Diagnostics area, SQLSTATE. */
   char m_sqlstate[SQLSTATE_LENGTH];
+  /** Diagnostics area, error count. */
   uint m_error_count;
+  /** Diagnostics area, warning count. */
   uint m_warning_count;
+  /** Diagnostics area, rows affected. */
   ulonglong m_rows_affected;
 
-  /* Optimizer */
+  /** Optimizer metric, number of rows sent. */
   ulonglong m_rows_sent;
+  /** Optimizer metric, number of rows examined. */
   ulonglong m_rows_examined;
+  /** Optimizer metric, number of temporary tables created on disk. */
   ulonglong m_created_tmp_disk_tables;
+  /** Optimizer metric, number of temporary tables created. */
   ulonglong m_created_tmp_tables;
+  /** Optimizer metric, number of full join. */
   ulonglong m_select_full_join;
+  /** Optimizer metric, number of full range join. */
   ulonglong m_select_full_range_join;
+  /** Optimizer metric, number of select range. */
   ulonglong m_select_range;
+  /** Optimizer metric, number of select range checks. */
   ulonglong m_select_range_check;
+  /** Optimizer metric, number of select scans. */
   ulonglong m_select_scan;
+  /** Optimizer metric, number of sort merge passes. */
   ulonglong m_sort_merge_passes;
+  /** Optimizer metric, number of sort ranges. */
   ulonglong m_sort_range;
+  /** Optimizer metric, number of sort rows. */
   ulonglong m_sort_rows;
+  /** Optimizer metric, number of sort scans. */
   ulonglong m_sort_scan;
+  /** Optimizer metric, number of 'no index used'. */
   ulonglong m_no_index_used;
+  /** Optimizer metric, number of 'no good index used'. */
   ulonglong m_no_good_index_used;
 };
 

=== modified file 'storage/perfschema/pfs_global.h'
--- a/storage/perfschema/pfs_global.h	2010-11-16 06:27:18 +0000
+++ b/storage/perfschema/pfs_global.h	2011-04-04 14:34:42 +0000
@@ -21,14 +21,31 @@
   Miscellaneous global dependencies (declarations).
 */
 
+/** True when the performance schema is initialized. */
 extern bool pfs_initialized;
+/** Total memory allocated by the performance schema, in bytes. */
 extern ulonglong pfs_allocated_memory;
 
 void *pfs_malloc(size_t size, myf flags);
+
+/**
+  Helper, to allocate an array of structures.
+  @param n number of elements in the array.
+  @param T type of an element.
+  @param f flags to use when allocating memory
+*/
 #define PFS_MALLOC_ARRAY(n, T, f) \
   reinterpret_cast<T*> (pfs_malloc((n) * sizeof(T), (f)))
+
+/** Free memory allocated with @sa pfs_malloc. */
 void pfs_free(void *ptr);
 
+/**
+  Compute a random index value in an interval.
+  @param ptr seed address
+  @param max_size maximun size of the interval
+  @return a random value in [0, max_size-1]
+*/
 inline uint randomized_index(const void *ptr, uint max_size)
 {
   static uint seed1= 0;

=== modified file 'storage/perfschema/pfs_instr.h'
--- a/storage/perfschema/pfs_instr.h	2011-02-14 14:23:55 +0000
+++ b/storage/perfschema/pfs_instr.h	2011-04-04 14:34:42 +0000
@@ -219,6 +219,7 @@ extern uint statement_stack_max;
 */
 #define PFS_MAX_ALLOC_RETRY 1000
 
+/** The maximun number of passes in @sa PFS_scan. */
 #define PFS_MAX_SCAN_PASS 2
 
 /**
@@ -232,24 +233,42 @@ extern uint statement_stack_max;
 struct PFS_scan
 {
 public:
+  /**
+    Initialize a new scan.
+    @param random a random index to start from
+    @param max_size the max size of the interval to scan
+  */
   void init(uint random, uint max_size);
 
+  /**
+    Predicate, has a next pass.
+    @return true if there is a next pass to perform.
+  */
   bool has_pass() const
   { return (m_pass < m_pass_max); }
 
+  /**
+    Iterator, proceed to the next pass.
+  */
   void next_pass()
   { m_pass++; }
   
+  /** First index for this pass. */
   uint first() const
   { return m_first[m_pass]; }
 
+  /** Last index for this pass. */
   uint last() const
   { return m_last[m_pass]; }
 
 private:
+  /** Current pass. */
   uint m_pass;
+  /** Maximum number of passes. */
   uint m_pass_max;
+  /** First element for each pass. */
   uint m_first[PFS_MAX_SCAN_PASS];
+  /** Last element for each pass. */
   uint m_last[PFS_MAX_SCAN_PASS];
 };
 

=== modified file 'storage/perfschema/pfs_server.h'
--- a/storage/perfschema/pfs_server.h	2011-02-14 14:23:55 +0000
+++ b/storage/perfschema/pfs_server.h	2011-04-04 14:34:42 +0000
@@ -91,54 +91,134 @@
   #define PFS_STATEMENTS_STACK_SIZE 10
 #endif
 
-
 /** Performance schema global sizing parameters. */
 struct PFS_global_param
 {
+  /** True if the performance schema is enabled. */
   bool m_enabled;
+  /**
+    Maximum number of instrumented mutex classes.
+    @sa mutex_class_lost.
+  */
   ulong m_mutex_class_sizing;
+  /**
+    Maximum number of instrumented rwlock classes.
+    @sa rwlock_class_lost.
+  */
   ulong m_rwlock_class_sizing;
+  /**
+    Maximum number of instrumented cond classes.
+    @sa cond_class_lost.
+  */
   ulong m_cond_class_sizing;
+  /**
+    Maximum number of instrumented thread classes.
+    @sa thread_class_lost.
+  */
   ulong m_thread_class_sizing;
   /**
     Maximum number of instrumented table share.
     @sa table_share_lost.
   */
   ulong m_table_share_sizing;
+  /**
+    Maximum number of instrumented file classes.
+    @sa file_class_lost.
+  */
   ulong m_file_class_sizing;
+  /**
+    Maximum number of instrumented mutex instances.
+    @sa mutex_lost.
+  */
   ulong m_mutex_sizing;
+  /**
+    Maximum number of instrumented rwlock instances.
+    @sa rwlock_lost.
+  */
   ulong m_rwlock_sizing;
+  /**
+    Maximum number of instrumented cond instances.
+    @sa cond_lost.
+  */
   ulong m_cond_sizing;
+  /**
+    Maximum number of instrumented thread instances.
+    @sa thread_lost.
+  */
   ulong m_thread_sizing;
   /**
     Maximum number of instrumented table handles.
     @sa table_lost.
   */
   ulong m_table_sizing;
+  /**
+    Maximum number of instrumented file instances.
+    @sa file_lost.
+  */
   ulong m_file_sizing;
+  /**
+    Maximum number of instrumented file handles.
+    @sa file_handle_lost.
+  */
   ulong m_file_handle_sizing;
+  /** Maximum number of rows per thread in table EVENTS_WAITS_HISTORY. */
   ulong m_events_waits_history_sizing;
+  /** Maximum number of rows in table EVENTS_WAITS_HISTORY_LONG. */
   ulong m_events_waits_history_long_sizing;
+  /** Maximum number of rows in table SETUP_ACTORS. */
   ulong m_setup_actor_sizing;
-  /** Maximum number of setup object records. */
+  /** Maximum number of rows in table SETUP_OBJECTS. */
   ulong m_setup_object_sizing;
+  /**
+    Maximum number of instrumented stage classes.
+    @sa stage_class_lost.
+  */
   ulong m_stage_class_sizing;
+  /** Maximum number of rows per thread in table EVENTS_STAGES_HISTORY. */
   ulong m_events_stages_history_sizing;
+  /** Maximum number of rows in table EVENTS_STAGES_HISTORY_LONG. */
   ulong m_events_stages_history_long_sizing;
+  /**
+    Maximum number of instrumented statement classes.
+    @sa statement_class_lost.
+  */
   ulong m_statement_class_sizing;
+  /** Maximum number of rows per thread in table EVENTS_STATEMENT_HISTORY. */
   ulong m_events_statements_history_sizing;
+  /** Maximum number of rows in table EVENTS_STATEMENTS_HISTORY_LONG. */
   ulong m_events_statements_history_long_sizing;
 };
 
+/**
+  Performance schema sizing values for the server.
+  This global variable is set when parsing server startup options.
+*/
 extern PFS_global_param pfs_param;
 
+/**
+  Initialize the performance schema.
+  @param param Size parameters to use.
+  @return A boostrap handle, or NULL.
+*/
 struct PSI_bootstrap*
 initialize_performance_schema(const PFS_global_param *param);
 
+/**
+  Initialize the performance schema ACL.
+  ACL is strictly enforced when the server is running in normal mode,
+  to enforce that only legal operations are allowed.
+  When running in boostrap mode, ACL restrictions are relaxed,
+  to allow the boostrap scripts to DROP / CREATE performance schema tables.
+  @sa ACL_internal_schema_registry
+  @param bootstrap True if the server is starting in bootstrap mode.
+*/
 void initialize_performance_schema_acl(bool bootstrap);
 
 void check_performance_schema();
 
+/**
+  Shutdown the performance schema.
+*/
 void shutdown_performance_schema();
 
 #endif

=== modified file 'storage/perfschema/pfs_setup_actor.cc'
--- a/storage/perfschema/pfs_setup_actor.cc	2010-07-02 16:15:37 +0000
+++ b/storage/perfschema/pfs_setup_actor.cc	2011-04-04 14:34:42 +0000
@@ -32,11 +32,19 @@
   @{
 */
 
+/** Size of the setup_actor instances array. @sa setup_actor_array */
 ulong setup_actor_max;
 
+/**
+  Setup_actor instances array.
+  @sa setup_actor_max
+*/
+
 PFS_setup_actor *setup_actor_array= NULL;
 
+/** Hash table for setup_actor records. */
 static LF_HASH setup_actor_hash;
+/** True if @c setup_actor_hash is initialized. */
 static bool setup_actor_hash_inited= false;
 
 /**

=== modified file 'storage/perfschema/pfs_timer.h'
--- a/storage/perfschema/pfs_timer.h	2011-02-14 14:23:55 +0000
+++ b/storage/perfschema/pfs_timer.h	2011-04-04 14:34:42 +0000
@@ -23,6 +23,7 @@
 #include <my_rdtsc.h>
 #include "pfs_column_types.h"
 
+/** Conversion factor, from micro seconds to pico seconds. */
 #define MICROSEC_TO_PICOSEC 1000000
 
 /**
@@ -33,41 +34,102 @@
 */
 struct time_normalizer
 {
+  /**
+    Get a time normalizer for a given timer.
+    @param timer_name the timer name
+    @return the normalizer for the timer
+  */
   static time_normalizer* get(enum_timer_name timer_name);
 
+  /** Timer value at server statup. */
   ulonglong m_v0;
+  /** Conversion factor from timer values to pico seconds. */
   ulonglong m_factor;
 
+  /**
+    Convert a wait from timer units to pico seconds.
+    @param wait a wait, expressed in timer units
+    @return the wait, expressed in pico seconds
+  */
   inline ulonglong wait_to_pico(ulonglong wait)
   {
     return wait * m_factor;
   }
 
+  /**
+    Convert a time from timer units to pico seconds.
+    @param t a time, expressed in timer units
+    @return the time, expressed in pico seconds
+  */
   inline ulonglong time_to_pico(ulonglong t)
   {
     return (t == 0 ? 0 : (t - m_v0) * m_factor);
   }
 
+  /**
+    Convert start / end times from timer units to pico seconds.
+    @param start start time, expressed in timer units
+    @param end end time, expressed in timer units
+    @param[out] pico_start start time, expressed in pico seconds
+    @param[out] pico_end end time, expressed in pico seconds
+    @param[out] pico_wait wait time, expressed in pico seconds
+  */
   void to_pico(ulonglong start, ulonglong end,
                ulonglong *pico_start, ulonglong *pico_end, ulonglong *pico_wait);
 };
 
+/**
+  Wait timer.
+  The timer used to measure all wait events.
+*/
 extern enum_timer_name wait_timer;
+/**
+  Stage timer.
+  The timer used to measure all stage events.
+*/
 extern enum_timer_name stage_timer;
+/**
+  Statement timer.
+  The timer used to measure all statement events.
+*/
 extern enum_timer_name statement_timer;
+/**
+  Timer information data.
+  Characteristics about each suported timer.
+*/
 extern MY_TIMER_INFO pfs_timer_info;
 
+/** Initialize the timer component. */
 void init_timers();
 
 extern "C"
 {
+  /** A timer function. */
   typedef ulonglong (*timer_fct_t)(void);
 }
 
+/**
+  Get a timer value, in pico seconds.
+  @param timer_name the timer to use
+  @return timer value, in pico seconds
+*/
 ulonglong get_timer_pico_value(enum_timer_name timer_name);
+/**
+  Get a timer value, in timer units.
+  @param timer_name the timer to use
+  @return timer value, in timer units
+*/
 ulonglong get_timer_raw_value(enum_timer_name timer_name);
+/**
+  Get a timer value and function, in timer units.
+  This function is useful when code needs to call the same timer several times.
+  The returned timer function can be invoked directly, which avoids having to
+  resolve the timer by name for each call.
+  @param timer_name the timer to use
+  @param[out] fct the timer function
+  @return timer value, in timer units
+*/
 ulonglong get_timer_raw_value_and_function(enum_timer_name timer_name, timer_fct_t *fct);
 
-
 #endif
 


Attachment: [text/bzr-bundle] bzr/marc.alff@oracle.com-20110404143442-yr2qiakzktqg181g.bundle
Thread
bzr commit into mysql-trunk branch (marc.alff:3325) Marc Alff4 Apr