| /********************************************************************** |
| // @@@ START COPYRIGHT @@@ |
| // |
| // 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. 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 |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| // |
| // @@@ END COPYRIGHT @@@ |
| **********************************************************************/ |
| /* -*-C++-*- |
| ***************************************************************************** |
| * |
| * File: ComExeTrace.h |
| * Description: Common interface for all executor (run-time) traces |
| * |
| * Created: 10/26/2011 |
| * Language: C++ |
| * |
| * |
| ***************************************************************************** |
| */ |
| #ifndef COMEXETRACE_H |
| #define COMEXETRACE_H |
| |
| #include "Platform.h" |
| #include "NABasicObject.h" |
| #include "Collections.h" |
| |
| // max of the trace name length and its field name length |
| #define MAX_TRACE_NAME_LEN 40 |
| #define MAX_FIELD_NAME_LEN 40 |
| |
| // forward declaration |
| class ExeTrace; |
| class ExeTraceInfo; |
| |
| //---------------------------------------------------------------------- |
| // This part is online document on how to add your trace to executor |
| // runtime trace repository and be displayed by sqstate |
| // |
| // To add trace information, the trace host class has to add/do the |
| // the following: |
| // 1. include "ComExeTrace.h" |
| // 2. add "void *traceRef_;" to keep the reference to the trace |
| // registration in the repository |
| // 3. define a static wrapper function, e.g. |
| // static Int32 getALine(void * mine, Int32 lineno, char * buf) |
| // { return ((ExScheduler *) mine)->printALiner(lineno, buf); } |
| // 4. define the print method named in the wrapper function, e.g. |
| // Int32 printALiner(Int32 lineno, char *buf) {...}; |
| // which prints all fields of one trace entry referenced by the lineno |
| // to buf and returns number of bytes added to the buffer. |
| // 5. use the following 3 methods in the ExeTraceInfo class to register |
| // and deregister the trace |
| // |
| // That's all. |
| // |
| // More about ExeTraceInfo methods used by trace host classes: |
| // |
| // Use this method to register trace to global trace info repository |
| // Int32 |
| // ExeTraceInfo::addTrace(const char * traceName, void * traceId, |
| // Int32 numEntries, Int32 numFields, void *target, |
| // GetALineProcPtr getALineProc, void * indexLoc, |
| // Int32 lineWidth, const char *desc, |
| // void **exeTrace) |
| // |
| // parameters: |
| // TraceName(i) - trace name to be shown at output. |
| // traceId(i) - unique reference to the trace from outside in the |
| // process, normally some address value |
| // numEntries(i) - the number of rows in the trace (array size) |
| // if the number of entries is dynamic, enter -1 |
| // numFields(i) - the number of field for each trace entry |
| // target(i) - normally target class "this" pointer |
| // getALineProc(i) - pointer to the function that can obtain one |
| // trace entry in string buffer |
| // indexLoc(i) - the address to obtain current trace index, can be NULL |
| // lineWidth(i) - the printed width for each trace entry in bytes |
| // desc(i) - the detailed information about the trace, its value |
| // will be copied to trace info repository |
| // exeTrace(o) - the reference of the trace in the repository, used |
| // later by caller to add trace columns and remove trace |
| // return value: |
| // 0 - trace added successfullly |
| // -1 - trace not added, could be deplicate or other reason |
| // note: |
| // the exeTrace will need to be save by caller for later reference |
| // |
| // Use this method to add trace column information, |
| // void |
| // ExeTraceInfo::addTraceField(void * exeTrace, const char * name, |
| // UInt32 fieldIdx, ExeTrace::FieldType fType) |
| // |
| // parameters: |
| // exeTrace(i) - the input obtained when the addTrace method was called. |
| // name(i) - column name. |
| // fieldIdx(i) - the sequence number of the column, starting from 0. |
| // fType(i) - one of the ExeTrace::FieldType enum values |
| // return value: none |
| // |
| // |
| // Use this method to remove the trace info when the objects contain |
| // the trace are to be deleted/deallocated. |
| // void |
| // ExeTraceInfo::removeTrace(void * exeTrace) |
| // |
| // parameters: |
| // exeTrace(i) - the input obtained when the addTrace method was called. |
| // return value: none |
| // |
| // note: |
| // to avoid invalid access to deleted trace, you must call this |
| // before deleting the host instance of the trace. |
| // |
| //---------------------------------------------------------------------- |
| |
| // types for pointers to methods |
| typedef Int32 (*GetALineProcPtr)(void *target, Int32 lineno, char *buf); |
| |
| // The following is not used now because we assume that all trace array |
| // indexes are of type Int32: |
| // |
| // typedef Int32 (*GetIndexProcPtr) (void); |
| |
| class ExeTrace |
| { |
| friend class ExeTraceInfo; |
| |
| public: |
| // typedef Int32 (ExeTrace::*GetALiner)(Int32 lineno, char *buf) const; |
| // typedef Int32 (ExeTrace::*GetIndex) (void) const; |
| |
| enum FieldType { |
| TR_CHAR = 1, |
| TR_INT16, |
| TR_INT32, |
| TR_INT64, |
| TR_STRING, |
| TR_POINTER32, |
| TR_POINTER64, |
| TR_TRANSID, |
| TR_TMSTAMP |
| }; |
| |
| struct TraceField { |
| char name_[MAX_FIELD_NAME_LEN]; |
| UInt32 nameLen_; |
| FieldType fieldType_; |
| }; |
| |
| ExeTrace(char *name, void *id, void *target, GetALineProcPtr getALineProc, |
| void *indexLoc, Int32 numEntries, Int32 lineLen, |
| const char *desc); |
| ~ExeTrace() {}; |
| |
| inline char * getTraceName() { return name_; }; |
| inline void * getTraceId() { return traceId_; }; |
| inline Int32 getNumEntries() { return numEntries_; }; |
| inline Int32 getNumFields() { return numFields_; }; |
| inline Int32 getLineWidth() { return lineWidth_; }; |
| inline Int32 getIndex() { return (indexLoc_ == NULL)? -1: |
| *((Int32 *)indexLoc_); }; |
| inline GetALineProcPtr getLineProc() { return getALineProc_; }; |
| inline void * getTarget() { return target_; }; |
| Int32 getTitleLineWidth(); |
| |
| private: |
| char name_[MAX_TRACE_NAME_LEN]; // name of the trace |
| void * traceId_; // identifer |
| void * target_; // target this pointer |
| GetALineProcPtr getALineProc_; // pointer to function sending one trace |
| // entry to given buffer |
| void * indexLoc_; // pointer to the trace index area |
| Int32 numEntries_; // size of the trace |
| Int32 numFields_; // size of the trace |
| Int32 lineWidth_; // number of bytes to sprint one trace entry |
| char * describes_; |
| TraceField fields_[1]; |
| }; |
| |
| class ExeTraceInfo : public NABasicObject |
| { |
| friend class ExeTrace; |
| public: |
| |
| // ctor |
| ExeTraceInfo(); |
| ~ExeTraceInfo(); |
| |
| // used by general public |
| // create and add the trace info |
| Int32 addTrace(const char * traceName, void * traceId, |
| Int32 numEntries, Int32 numFields, void *target, |
| GetALineProcPtr getALineProc, void *indexLoc, |
| Int32 lineWidth, const char *desc, |
| void **exeTrace); |
| // add trace field info |
| void addTraceField(void *exeTrace, const char * fieldName, |
| UInt32 fieldIdx, ExeTrace::FieldType fType); |
| // unregister the given trace |
| void removeTrace(void * exeTrace); |
| |
| // all kinds of helpers |
| bool isRegistered(ExeTrace *trace) |
| { return exeTraces_.contains(trace) == TRUE; }; |
| bool isValidTraceId(void *traceId) { return true; }; // tbd |
| |
| Int32 getExeTraceInfoAll(char *outBuf, Int32 maxBufLen, Int32 *bufLen, |
| Int32 startTid=0); |
| Int32 getExeTraceAll(char *outBuf, Int32 maxBufLen, Int32 *bufLen, |
| Int32 startTid=0); |
| void * getExeTraceId(char *name, Int32 nameLen) const; |
| Int32 getExeTraceInfoById(void *traceId, char *buf, Int32 maxBufLen, |
| Int32 *bufLen); |
| |
| Int32 getExeTraceById(void *traceId, char *buf, Int32 maxBufLen, |
| Int32 *bufLen); |
| |
| private: |
| LIST(ExeTrace *) exeTraces_; |
| |
| }; |
| |
| #endif // COMEXETRACE_H |