sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // Symbian SQL Resource Profiler header file
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @file
sl@0:  @internalComponent
sl@0: */
sl@0: #ifndef __SQLRESOURCEPROFILER_H__
sl@0: #define __SQLRESOURCEPROFILER_H__
sl@0: 
sl@0: #include <sqldb.h>
sl@0: 
sl@0: /**
sl@0: Symbian SQL profiling interface.
sl@0: TSqlResourceProfiler class is used for:
sl@0: 
sl@0: @code
sl@0: 
sl@0:  -	Retrieving the current state of the SQL server heap and SQLite heap stats.
sl@0:    	Example:
sl@0: 		RSqlDatabase db;
sl@0: 		//initialize the db object....
sl@0: 		...
sl@0: 		TSqlResourceProfiler profiler(db);
sl@0: 		profiler.Start(TSqlResourceProfiler::ESqlCounterMemory);//Start the profiling
sl@0: 		profiler.Reset(TSqlResourceProfiler::ESqlCounterMemory);//Zero the porfiling counters
sl@0: 		....
sl@0: 		profiler.Stop(TSqlResourceProfiler::ESqlCounterMemory); //Stop the profiling
sl@0: 		TBuf8<128> res;
sl@0: 		profiler.Query(TSqlResourceProfiler::ESqlCounterMemory, res);
sl@0: 	The format of the retrieved counters is:   
sl@0: 		"<Allocated cells count>;<Allocated size>;<Free space>;<Largest block size>;
sl@0: 		 <SQLite: allocated cnt>;<SQLite: reallocated cnt>;<SQLite: freed cnt>;
sl@0: 		 <SQLite: allocated bytes>;<SQLite: freed bytes>;
sl@0: 		 <SQLite: time spent in alloc(), us>;<SQLite: time spent in realloc(), us>;<SQLite: time spent in free(), us>;";
sl@0: 	This service can be used only if the SQL code is compiled with the _SQLPROFILER macro.
sl@0: 		
sl@0:  - Retrieving the size of the biggest memory block ever allocated by the Symbian SQL server and SQLite.
sl@0:    	Example:
sl@0: 		RSqlDatabase db;
sl@0: 		//initialize the db object....
sl@0: 		...
sl@0: 		TSqlResourceProfiler profiler(db);
sl@0: 		.....
sl@0: 		profiler.Start(TSqlResourceProfiler::ESqlCounterMaxAlloc);//Start the profiling
sl@0: 		.....
sl@0: 		TBuf8<32> res;
sl@0: 		profiler.Query(TSqlResourceProfiler::ESqlCounterMaxAlloc, res);
sl@0: 		...
sl@0: 		profiler.Reset(TSqlResourceProfiler::ESqlCounterMaxAlloc);//Reset the profiling 
sl@0: 		....
sl@0: 		profiler.Stop(TSqlResourceProfiler::ESqlCounterMaxAlloc);
sl@0: 	The format of the retrieved counters is: 
sl@0: 		"<SQL server - max alloc size>;<SQLite - max alloc size>";
sl@0: 	This service can be used only if the SQL code is compiled with the _SQLPROFILER macro.
sl@0: 
sl@0:  - Retrieving the number of the file system calls made by the OS porting layer and the amount of written/read data.
sl@0:   	Example:
sl@0: 		RSqlDatabase db;
sl@0: 		//initialize the db object....
sl@0: 		...
sl@0: 		TSqlResourceProfiler profiler(db);
sl@0: 		.....
sl@0: 		profiler.Start(TSqlResourceProfiler::ESqlCounterFileIO);//Start the profiling
sl@0: 		.....
sl@0: 		TBuf8<300> res;
sl@0: 		profiler.Query(TSqlResourceProfiler::ESqlCounterFileIO, res);
sl@0: 		.....
sl@0: 		profiler.Reset(TSqlResourceProfiler::ESqlCounterFileIO);//Reset the profiling 
sl@0: 		....
sl@0: 		profiler.Stop(TSqlResourceProfiler::ESqlCounterFileIO);
sl@0: 	The format of the retrieved data is: 
sl@0: 	"<RFileBuf64::Create() cnt>;<RFileBuf64::Open() cnt>;<RFileBuf64::Close() cnt>;<RFs::Delete() cnt>;
sl@0: 	 <RFileBuf64::Read() cnt>;<RFileBuf64::Write() cnt>;<RFileBuf64::Seek() cnt>;<RFileBuf64::Size() cnt>;<RFileBuf64::SetSize() cnt>;
sl@0: 	 <RFileBuf64::Flush() cnt>;<RFile64::Drive() cnt>;<RFileBuf64::AdoptFromClient() cnt>;<RFs::Close() cnt>;
sl@0: 	 <RFs::Connect() cnt>;<RFs::GetSystemDrive() cnt>;<RFs::CreatePrivatePath() cnt>;<RFs::PrivatePath() cnt>;
sl@0: 	 <RFs::VolumeIoParam() cnt>;<RFs::Entry() cnt>;<RFs::Att() cnt>;<RFileBuf64::Temp() cnt>;<0>;
sl@0: 	 <bytes written>;<bytes read>;"
sl@0: 	Note that currently the file operations are buffered, so the retrieved results will be about the operations executed on a
sl@0: 	RFileBuf64 objects.
sl@0: 	This service can be used only if the SQL code is compiled with the _SQLPROFILER macro.
sl@0: 
sl@0:  - Retrieving information regading the current SQL/SQLite configuration.
sl@0:   	Example:
sl@0: 		RSqlDatabase db;
sl@0: 		//initialize the db object....
sl@0: 		...
sl@0: 		TSqlResourceProfiler profiler(db);
sl@0: 		TBuf8<128> res;
sl@0: 		profiler.Query(TSqlResourceProfiler::ESqlCounterConfig, res);
sl@0: 	The format of the retrieved numbers is:   
sl@0: 		"<Cache size in pages>;<Page size in bytes>;<Database encoding>;<Default soft heap limit>;<SQLite vacuum mode>";
sl@0: 
sl@0:  - Retrieving the number of the OS porting layer calls made by SQLite.
sl@0:   	Example:
sl@0: 		RSqlDatabase db;
sl@0: 		//initialize the db object....
sl@0: 		...
sl@0: 		TSqlResourceProfiler profiler(db);
sl@0: 		.....
sl@0: 		profiler.Start(TSqlResourceProfiler::ESqlCounterOsCall);//Start the profiling
sl@0: 		.....
sl@0: 		TBuf8<300> res;
sl@0: 		profiler.Query(TSqlResourceProfiler::ESqlCounterOsCall, res);
sl@0: 		.....
sl@0: 		profiler.Reset(TSqlResourceProfiler::ESqlCounterOsCall);//Reset the profiling 
sl@0: 		....
sl@0: 		profiler.Stop(TSqlResourceProfiler::ESqlCounterOsCall);
sl@0: 	The format of the retrieved data is: 
sl@0: 	"<file close cnt>;<file read cnt>;<file write cnt>;<file truncate cnt>;
sl@0: 	 <file sync cnt>;<file size cnt>;<file lock cnt>;<file unlock cnt>;<file check reserved lock cnt>;
sl@0: 	 <file i/o control cnt>;<file sector size cnt>;<file device characteristics cnt>;<vfs open cnt>;
sl@0: 	 <vfs delete cnt>;<vfs access cnt>;<vfs full path name cnt>;<vfs randomness cnt>;
sl@0: 	 <vfs sleep cnt>;<vfs current time cnt>;<vfs get last error cnt>;"
sl@0: 	This service can be used only if the SQL code is compiled with the _SQLPROFILER macro.
sl@0:    	
sl@0:  - Retrieving the OS porting layer call times in microseconds per call type.
sl@0:   	Example:
sl@0: 		RSqlDatabase db;
sl@0: 		//initialize the db object....
sl@0: 		...
sl@0: 		TSqlResourceProfiler profiler(db);
sl@0: 		.....
sl@0: 		profiler.Start(TSqlResourceProfiler::ESqlCounterOsCallTime);//Start the profiling
sl@0: 		.....
sl@0: 		TBuf8<300> res;
sl@0: 		profiler.Query(TSqlResourceProfiler::ESqlCounterOsCallTime, res);
sl@0: 		.....
sl@0: 		profiler.Reset(TSqlResourceProfiler::ESqlCounterOsCallTime);//Reset the profiling 
sl@0: 		....
sl@0: 		profiler.Stop(TSqlResourceProfiler::ESqlCounterOsCallTime);
sl@0: 	The format of the retrieved data is: 
sl@0: 	"<file close time>;<file read time>;<file write time>;<file truncate time>;
sl@0: 	 <file sync time>;<file size time>;<file lock time>;<file unlock time>;<file check reserved lock time>;
sl@0: 	 <file i/o control time>;<file sector size time>;<file device characteristics time>;<vfs open time>;
sl@0: 	 <vfs delete time>;<vfs access time>;<vfs full path name time>;<vfs randomness time>;
sl@0: 	 <vfs sleep time>;<vfs current time time>;<vfs get last error time>;"
sl@0: 	This service can be used only if the SQL code is compiled with the _SQLPROFILER macro.
sl@0: 
sl@0:  - Retrieving the OS porting layer call times in microseconds per call type plus adding a log entry 
sl@0:    for each call. The returned information is the same as for the previous profiling type.
sl@0:    But for each OS porting layer call an entry is added to the log file (epocwind.out).
sl@0:    The format of the log entry is:
sl@0:    	<'M'/'J'>,<'Call Id'>,<#Counter>,<Call Counter>,<File Offset>,<Bytes>,<Ticks>,<Bytes Total>,<Ticks Total>
sl@0:    Note: ESqlCounterOsCallDetails and ESqlCounterOsCallTime profiles cannot be used together.
sl@0: 
sl@0:  - Retrieving the number of the IPC calls and IPC read/write operations.
sl@0:   	Example:
sl@0: 		RSqlDatabase db;
sl@0: 		//initialize the db object....
sl@0: 		...
sl@0: 		TSqlResourceProfiler profiler(db);
sl@0: 		.....
sl@0: 		profiler.Start(TSqlResourceProfiler::ESqlCounterIpc);//Start the profiling
sl@0: 		.....
sl@0: 		TBuf8<300> res;
sl@0: 		profiler.Query(TSqlResourceProfiler::ESqlCounterIpc, res);
sl@0: 		.....
sl@0: 		profiler.Reset(TSqlResourceProfiler::ESqlCounterIpc);//Reset the profiling 
sl@0: 		....
sl@0: 		profiler.Stop(TSqlResourceProfiler::ESqlCounterIpc);
sl@0: 	The format of the retrieved data is: 
sl@0: 	"<IPC call cnt>;<IPC write cnt>;<IPC read cnt>;<IPC write bytes>;<IPC read bytes>;
sl@0: 	This service can be used only if the SQL code is compiled with the _SQLPROFILER macro.
sl@0:    	
sl@0:  - Tracing the executed SQL statements and IPC calls.
sl@0:    The folowing tracing configurations can be used (pased as a configuration parameter in TSqlResourceProfiler::Start()):
sl@0:    - "L0" - [default] tracing level 0. IPC traces disabled;
sl@0:    - "L1" - tracing level 1. Only the most important IPC calls are traced:
sl@0:             ESqlSrvDbExec8, ESqlSrvDbExec16, ESqlSrvDbScalarFullSelect16, ESqlSrvStmtExec,
sl@0:             ESqlSrvStmtAsyncExec, ESqlSrvStmtBindExec, ESqlSrvStmtAsyncBindExec, ESqlSrvStmtNext,
sl@0:             ESqlSrvStmtBindNext;
sl@0:    - "L2" - tracing level 2. All IPC calls traced;
sl@0:    - "S0" - [default] SQL statement tracing is off; 
sl@0:    - "S1" - SQL statement tracing is on;
sl@0:     Example:
sl@0:         RSqlDatabase db;
sl@0:         //initialize the db object....
sl@0:         ...
sl@0:         TSqlResourceProfiler profiler(db);
sl@0:         .....
sl@0:         _LIT8(KConfig, "<config string>");
sl@0:         profiler.Start(TSqlResourceProfiler::ESqlCounterTrace, &KConfig);//Start the profiling
sl@0:         .....
sl@0:         profiler.Stop(TSqlResourceProfiler::ESqlCounterTrace);
sl@0:     The format of the traces is:
sl@0:     - SQL statement trace:
sl@0:       <DbHandle>¬<TimeFromStart>¬SQL¬Prepare/Exec¬<SQL statemment>
sl@0:     - "Database create" trace:
sl@0:       <DbHandle>¬<TimeFromStart>¬CRE¬<database file path>
sl@0:     - "Database open" trace:
sl@0:       <DbHandle>¬<TimeFromStart>¬OPN¬<database file path>
sl@0:     - "Database close" trace:
sl@0:       <DbHandle>¬<TimeFromStart>¬CSE
sl@0:     - "IPC call error" trace:
sl@0:       <DbHandle>¬<TimeFromStart>¬ERR¬<IPC counter>¬<IPC call name>¬err=<error code>
sl@0:     - "IPC call level 1 or level 2" trace:
sl@0:       <DbHandle>¬<TimeFromStart>¬IPC¬<IPC counter>¬<IPC call name>¬<TotalExecTime>¬<ExecTime>¬<ThisCallIpcCount>¬..¬rc=<ret code>
sl@0:     This service can be used only if the SQL code is compiled with the _SQLPROFILER macro.
sl@0: @endcode
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: class TSqlResourceProfiler
sl@0: 	{
sl@0: public:
sl@0: 	enum TSqlCounter
sl@0: 		{
sl@0: 		ESqlCounterFileIO,
sl@0: 		ESqlCounterOsCall,
sl@0: 		ESqlCounterOsCallTime,
sl@0: 		ESqlCounterOsCallDetails,
sl@0: 		ESqlCounterIpc,
sl@0: 		ESqlCounterMemory,
sl@0: 		ESqlCounterMaxAlloc,
sl@0: 		ESqlCounterConfig,
sl@0: 		ESqlCounterTrace
sl@0: 		};
sl@0: 	IMPORT_C TSqlResourceProfiler(RSqlDatabase& aDatabase);
sl@0: 	IMPORT_C TInt Start(TSqlCounter aCounterType, const TDesC8* aParam = NULL);
sl@0: 	IMPORT_C TInt Stop(TSqlCounter aCounterType);
sl@0: 	IMPORT_C TInt Reset(TSqlCounter aCounterType);
sl@0: 	IMPORT_C TInt Query(TSqlCounter aCounterType, TDes8& aResult);
sl@0: 	
sl@0: private:	
sl@0: 	RSqlDatabase iDatabase;
sl@0: 	
sl@0: 	};
sl@0: 
sl@0: #endif //__SQLRESOURCEPROFILER_H__