Preliminary version of Trace API header. Not integrated yet, for peer review

src/jrd/ntrace.h

@@ -0,0 +1,155 @@
+/*
+ *	PROGRAM:	JRD Access Method
+ *	MODULE:		ntrace.h
+ *	DESCRIPTION:	Trace API header
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ * You may obtain a copy of the Licence at
+ * http://www.gnu.org/licences/lgpl.html
+ * 
+ * As a special exception this file can also be included in modules
+ * with other source code as long as that source code has been 
+ * released under an Open Source Initiative certificed licence.  
+ * More information about OSI certification can be found at: 
+ * http://www.opensource.org 
+ * 
+ * This module is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public Licence for more details.
+ * 
+ * This module was created by members of the firebird development 
+ * team.  All individual contributions remain the Copyright (C) of 
+ * those individuals and all rights are reserved.  Contributors to 
+ * this file are either listed below or can be obtained from a CVS 
+ * history command.
+ *
+ *  Created by: Nickolay Samofatov <nickolay@broadviewsoftware.com>
+ *
+ *  Contributor(s):
+ * 
+ *
+ *  $Id: ntrace.h,v 1.1 2004-04-04 07:40:58 skidder Exp $
+ *
+ */
+
+/* Keep this header written using C language, please */
+
+
+/* Version of API, used for version fields in TraceDatabase and TracePlugin structures */
+#define NTRACE_VERSION 1
+
+#define NTRACE_TRUE 1
+#define NTRACE_FALSE 0
+
+/* Database objects*/
+
+typedef int ntrace_connection_t;
+
+typedef int ntrace_transaction_t;
+
+typedef int ntrace_procedure_t;
+
+typedef void* ntrace_statement_t;
+
+/* Plugin-specific argument. Passed by the engine to each hook */
+typedef void* ntrace_object_t;
+
+/* Structure version*/
+typedef int ntrace_version_t;
+
+/* Boolean type */
+typedef int ntrace_boolean_t;
+
+/* Performance counter */
+typedef unsigned int ntrace_counter_t;
+
+/* Used for arrays with binary data */
+typedef unsigned char ntrace_byte_t;
+
+/* Lengths of various arrays and structures */
+typedef unsigned int ntrace_size_t;
+
+/* Performance counters for individual table */
+struct TableStats {
+	ntrace_counter_t tin_id; /* Relation ID */
+	ntrace_counter_t tin_indexed_reads;
+	ntrace_counter_t tin_nonindexed_reads;
+	ntrace_counter_t tin_updates;
+	ntrace_counter_t tin_deletes;
+	ntrace_counter_t tin_inserts;
+};
+
+/* Performance statistics for operation */
+struct PerformanceInfo {
+	ntrace_counter_t pin_time; /* Total operation time in milliseconds */
+	ntrace_counter_t pin_reads; /* Page reads for operation */
+	ntrace_counter_t pin_writes; /* Page writes for operation */
+	ntrace_counter_t pin_fetches; /* Page fetches from OS */
+
+	ntrace_size_t pin_count; /* Number of relations involved in analysis */
+	struct TableInfo *pin_tables; /* Pointer to array with table stats */
+};
+
+/* Get error string for hook failure that happened */
+typedef char* (*ntrace_get_error)(ntrace_object_t tpl_object);
+
+/* Create/close attachment */
+typedef ntrace_boolean_t (*ntrace_event_attach)(ntrace_object_t tpl_object, 
+	ntrace_connection_t connection, ntrace_size_t dpb_length, const ntrace_byte_t *dpb);
+typedef ntrace_boolean_t (*ntrace_event_detach)(ntrace_object_t tpl_object, 
+	ntrace_connection_t connection);
+
+/* Start/end transaction */
+typedef ntrace_boolean_t (*ntrace_event_transaction_start)(ntrace_object_t tpl_object, 
+	ntrace_connection_t connection, ntrace_transaction_t transaction, 
+	ntrace_size_t tpb_length, const ntrace_byte_t* tpb);
+typedef ntrace_boolean_t (*ntrace_event_transaction_end)(ntrace_object_t tpl_object,
+	ntrace_connection_t connection, ntrace_transaction_t transaction, 
+	ntrace_boolean_t commit, ntrace_boolean_t retain_context);
+
+/* DSQL statement lifecycle */
+typedef ntrace_boolean_t (*ntrace_event_dsql_prepare)(ntrace_object_t tpl_object, 
+	ntrace_connection_t connection, ntrace_transaction_t transaction,
+	ntrace_statement_t statement, const char* sql, ntrace_counter_t time_millis,
+	ntrace_size_t access_path_length, const ntrace_byte_t* access_path);
+typedef ntrace_boolean_t (*ntrace_event_dsql_execute)(ntrace_object_t tpl_object, 
+	ntrace_connection_t connection, ntrace_transaction_t transaction,
+	ntrace_statement_t statement, PerformanceInfo *info);
+typedef ntrace_boolean_t (*ntrace_event_dsql_fetch)(ntrace_object_t tpl_object, 
+	ntrace_connection_t connection, ntrace_transaction_t transaction,
+	ntrace_statement_t statement, PerformanceInfo *info, ntrace_counter_t records_fetched);
+typedef ntrace_boolean_t (*ntrace_event_dsql_free)(ntrace_object_t tpl_object, 
+	ntrace_connection_t connection, ntrace_transaction_t transaction,
+	ntrace_statement_t statement, unsigned short option);
+
+/* Procedure execution */
+typedef ntrace_boolean_t (*ntrace_event_proc_execute)(ntrace_object_t tpl_object, 
+	ntrace_connection_t connection, ntrace_transaction_t transaction,
+	ntrace_procedure_t procedure, PerformanceInfo *info);
+
+/* API of trace plugin. Used to deliver notifications for each database */
+struct TracePlugin {
+	/* API version */
+	ntrace_version_t tpl_version;
+	/* Object pointer to pass to each hook */
+	ntrace_object_t tpl_object;
+
+	/* Function to return error string for hook failure */
+	ntrace_get_error tpl_get_error;
+
+	/* Events supported */
+	ntrace_event_attach tpl_event_attach;
+	ntrace_event_detach tpl_event_detach;
+	ntrace_event_tra tpl_event_transaction_start;
+	ntrace_event_detach tpl_event_transaction_end;
+	ntrace_event_dsql_prepare tpl_event_dsql_prepare;
+	ntrace_event_dsql_execute tpl_event_dsql_execute;
+	ntrace_event_dsql_fetch tpl_event_dsql_fetch;
+	ntrace_event_dsql_free tpl_event_dsql_free;
+
+	ntrace_event_proc_execute tpl_event_proc_execute;
+};