util/queue/QueueInterface.h

Go to the documentation of this file.
00001 /*----------------------------------------------------------------------------
00002 Name:      QueueInterface.h
00003 Project:   xmlBlaster.org
00004 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
00005 Author:    "Marcel Ruff" <xmlBlaster@marcelruff.info>
00006 Comment:   Interface for transient or persistent queue implementations
00007            with priority and time stamp sorting
00008 Note:      The gcc and icc (>=8) both define __GNUC__
00009 See:       http://www.xmlblaster.org/xmlBlaster/doc/requirements/client.c.queue.html
00010 See:       http://www.xmlblaster.org/xmlBlaster/doc/requirements/queue.html
00011 -----------------------------------------------------------------------------*/
00012 #ifndef I_QUEUE_QueueInterface_h
00013 #define I_QUEUE_QueueInterface_h
00014 
00015 #include "util/helper.h" /* BlobHolder. basicDefs.h: for int64_t (C99), Dll_Export, bool etc. */
00016 
00017 #ifdef __cplusplus
00018 #ifndef XMLBLASTER_C_COMPILE_AS_CPP /* 'g++ -DXMLBLASTER_C_COMPILE_AS_CPP ...' allows to compile the lib as C++ code */
00019 extern "C" {
00020 #endif
00021 #endif
00022 
00023 /*const int QUEUE_ENTRY_EMBEDDEDTYPE_LEN = 28; -> not supported with C90 to be used for array sizes */
00024 #define QUEUE_ENTRY_EMBEDDEDTYPE_LEN 28
00025 
00026 #define QUEUE_PREFIX_MAX 20
00027 #define QUEUE_DBNAME_MAX 256
00028 #define QUEUE_ID_MAX 256
00029 
00033 typedef struct {
00034    char dbName[QUEUE_DBNAME_MAX];      
00035    char queueName[QUEUE_ID_MAX];       
00036    char tablePrefix[QUEUE_PREFIX_MAX]; 
00037    int32_t maxNumOfEntries;            
00038    int64_t maxNumOfBytes;              
00039    XmlBlasterLogging logFp;            
00040    XMLBLASTER_LOG_LEVEL logLevel;      
00041    void *userObject;                   
00042 } QueueProperties;
00043 
00047 typedef struct {
00048    int64_t uniqueId;        
00049    int16_t priority;        
00050    bool isPersistent;       
00051    int64_t sizeInBytes;     
00052    char embeddedType[QUEUE_ENTRY_EMBEDDEDTYPE_LEN]; 
00053    BlobHolder embeddedBlob; 
00054 } QueueEntry;
00055 
00059 typedef struct QueueEntryStructArr {
00060    size_t len;
00061    QueueEntry *queueEntryArr;
00062 } QueueEntryArr;
00063 
00064 struct I_QueueStruct;
00065 typedef struct I_QueueStruct I_Queue;
00066 
00068 typedef bool  ( * I_QueueInitialize)(I_Queue *queueP, const QueueProperties *queueProperties, ExceptionStruct *exception);
00069 typedef void  ( * I_QueueShutdown)(I_Queue **queuePP, ExceptionStruct *exception);
00070 typedef bool  ( * I_QueueDestroy)(I_Queue **queuePP, ExceptionStruct *exception);
00071 typedef const QueueProperties *( * I_QueueGetProperties)(I_Queue *queueP);
00072 typedef void  ( * I_QueuePut)(I_Queue *queueP, const QueueEntry *queueEntry, ExceptionStruct *exception);
00073 typedef QueueEntryArr *( * I_QueuePeekWithSamePriority)(I_Queue *queueP, int32_t maxNumOfEntries, int64_t maxNumOfBytes, ExceptionStruct *exception);
00074 typedef int32_t ( * I_QueueRandomRemove)(I_Queue *queueP, const QueueEntryArr *queueEntryArr, ExceptionStruct *exception);
00075 typedef bool  ( * I_QueueClear)(I_Queue *queueP, ExceptionStruct *exception);
00076 typedef bool  ( * I_QueueEmpty)(I_Queue *queueP);
00077 typedef int32_t ( * I_QueueNumOfEntries)(I_Queue *queueP);
00078 typedef int32_t ( * I_QueueMaxNumOfEntries)(I_Queue *queueP);
00079 typedef int64_t ( * I_QueueNumOfBytes)(I_Queue *queueP);
00080 typedef int64_t ( * I_QueueMaxNumOfBytes)(I_Queue *queueP);
00081 
00088 struct I_QueueStruct {
00089   /* public: */
00090    void *userObject; /* A client can use this pointer to point to any client specific information */
00091 
00097    I_QueueGetProperties getProperties;
00098 
00113    I_QueuePut put;
00114 
00129    I_QueuePeekWithSamePriority peekWithSamePriority;
00130 
00144    I_QueueRandomRemove randomRemove;
00145 
00154    I_QueueClear clear;
00155 
00163    I_QueueShutdown shutdown;
00164 
00170    I_QueueDestroy destroy;
00171 
00177    I_QueueNumOfEntries getNumOfEntries;
00178 
00184    I_QueueMaxNumOfEntries getMaxNumOfEntries;
00185 
00194    I_QueueNumOfBytes getNumOfBytes;
00195 
00201    I_QueueMaxNumOfBytes getMaxNumOfBytes;
00202 
00208    I_QueueEmpty empty;
00209 
00214    XMLBLASTER_LOG_LEVEL logLevel;
00215 
00220    XmlBlasterLogging log;
00221 
00222   /* private: */
00223 
00228    I_QueueInitialize initialize;
00229    bool isInitialized;  
00230    void *privateObject; 
00231 };
00232 
00255 Dll_Export extern I_Queue *createQueue(const QueueProperties *queueProperties, ExceptionStruct *exception);
00256 
00262 extern Dll_Export void freeQueueEntryArr(QueueEntryArr *queueEntryArr);
00263 
00269 extern Dll_Export void freeQueueEntryArrInternal(QueueEntryArr *queueEntryArr);
00270 
00276 extern Dll_Export void freeQueueEntry(QueueEntry *queueEntry);
00277 
00285 extern Dll_Export char *queueEntryToXml(QueueEntry *queueEntry, int maxContentDumpLen);
00286 
00291 extern Dll_Export void freeEntryDump(char *queueDump);
00292 
00293 #ifdef __cplusplus
00294 #ifndef XMLBLASTER_C_COMPILE_AS_CPP
00295 }
00296 #endif
00297 #endif
00298 
00299 #endif /* I_QUEUE_QueueInterface_h */
00300