00001 /*! \file kogmo_rtdb_types.h 00002 * \brief Types for the contained Objects in the Real-time Vehicle Database 00003 * 00004 * Copyright (c) 2003-2006 Matthias Goebl <matthias.goebl*goebl.net> 00005 * Lehrstuhl fuer Realzeit-Computersysteme (RCS) 00006 * Technische Universitaet Muenchen (TUM) 00007 */ 00008 00009 #ifndef KOGMO_RTDB_TYPES_H 00010 #define KOGMO_RTDB_TYPES_H 00011 00012 #include <inttypes.h> /* (u)int??_t */ 00013 00014 // fallback for me (Matthias), please look at kogmo_objects/kogmo_rtdb_obj_packing.h ! 00015 #if defined(__GNUC__) && !defined(PACKED_struct) 00016 #define PACKED_struct struct __attribute__((packed)) 00017 #endif 00018 00019 #ifndef KOGMO_RTDB_REV 00020 #define KOGMO_RTDB_REV 540 00021 #endif 00022 00023 00024 #ifdef __cplusplus 00025 namespace KogniMobil { 00026 extern "C" { 00027 #endif 00028 00029 00030 /*! \defgroup kogmo_rtdb_types C-Types and Structures for Database Objects 00031 * \brief These Types are used as Parameters in Calls to the Database-API 00032 * and should be used in Database Objects if possible. 00033 */ 00034 /*@{*/ 00035 00036 00037 /*! \brief ID for Objects within the Database that are unique during database 00038 * runtime. 00039 * IDs are not unique between database restarts (so far). 00040 * 00041 * Please note: 00042 * - This could become int64_t some day 00043 * - So please use this type and print it with 00044 * \code printf("%lli",(long long int)oid) \endcode 00045 * - 0 is always invalid and may represent unused entries or 00046 * "not found" as return value 00047 * - <0 represents errors as return value 00048 * 00049 * TODO: 00050 * - Decide what to for Object-Interchange between Vehicles: 00051 * - Define separate ID-Ranges 00052 * - When synchronizing (and security checking!) foreign objects, use ID mapping 00053 */ 00054 typedef int32_t kogmo_rtdb_objid_t; 00055 00056 00057 /*! \brief Type-Identifier for Objects within the Database that is unique 00058 * forever. 00059 * This is to avoid missinterpretation when using old data sets. 00060 * 00061 * Please note: 00062 * - This could become int64_t some day 00063 * - So please use this type and print it with 00064 * \code printf("%lli",(long long int)otype) \endcode 00065 * - 0 is always invalid and may represent unused entries or 00066 * "not found" as return value. As search parameter it means "any type". 00067 * - 1 is "unknown object" (only basedata ist specified, length 00068 * of additional data is free 00069 * - <0 represents errors as return value 00070 * 00071 * TODO: 00072 * - Define 00073 * - Define Ranges for separate Sub-Projects 00074 * - Define Version-Information 00075 */ 00076 typedef int32_t kogmo_rtdb_objtype_t; 00077 00078 00079 /*! \brief Size-Specification for Objects within the Database. 00080 * 00081 * Please note: 00082 * - This could become int64_t some day 00083 * - So please use this type and print it with 00084 * \code printf("%lli",(long long int)osize) \endcode 00085 * - <0 represents errors as return value 00086 * 00087 * TODO: 00088 * - use consequently 00089 */ 00090 typedef int32_t kogmo_rtdb_objsize_t; 00091 00092 00093 00094 00095 //! see kogmo_rtdb_obj_info_t 00096 #define KOGMO_RTDB_DEFAULT_HISTORY_INTERVAL 10.0 00097 //! see kogmo_rtdb_obj_info_t 00098 #define KOGMO_RTDB_DEFAULT_MAX_CYCLETIME 0.030 00099 //! how long to keep deleted objects if history is shorter 00100 //! (the manager has an additional purge interval of 0.25 sec) 00101 #define KOGMO_RTDB_KEEP_DELETED_INTERVAL 0.25 00102 00103 //! maximum size for object names in kogmo_rtdb_obj_info_t 00104 //! (including terminating null-byte) 00105 #define KOGMO_RTDB_OBJMETA_NAME_MAXLEN 32 00106 00107 //! \brief Type for a Object-Name 00108 //! (see kogmo_rtdb_obj_info_t) 00109 typedef char kogmo_rtdb_objname_t [KOGMO_RTDB_OBJMETA_NAME_MAXLEN]; 00110 00111 //! see 00112 #define KOGMO_RTDB_OBJIDLIST_MAX 1000 00113 /*! \brief Type for a pre-allocated Array to receive the results of 00114 * kogmo_rtdb_obj_readdatameta(). 00115 * It is terminated by a 0-element. 00116 */ 00117 typedef kogmo_rtdb_objid_t kogmo_rtdb_objid_list_t [KOGMO_RTDB_OBJIDLIST_MAX+1]; 00118 00119 00120 00121 /*! \brief Data Block that contains Object-Metadata. 00122 * The Metadata of an Object should not (or only very slowly) change 00123 * during its livetime. 00124 * 00125 * \note 00126 * - So far, metadata-updates are forbidden 00127 * - If something changes, put it into the data-section 00128 * - metadata-updates would require additional triggers for metadata-changes, 00129 * that would increase complexibility 00130 * - So far, the parent-ID is fixed, because it is included in the metadata. 00131 * Until now, if the parent changes, the object has to be deleted and 00132 * inserted with a new parent. Applications will show if this works. 00133 * 00134 * Fields are marked as follows: 00135 * - (U) Fields that can be filled by the user 00136 * - (D) Fields that will be managed by the database and will be overwritten 00137 * - (I) Fields that are used internally by the database and should be ignored 00138 */ 00139 00140 typedef PACKED_struct 00141 { 00142 kogmo_rtdb_objid_t oid; 00143 //!< (D) Unique Object-ID, will be automatically created and overwritten 00144 00145 kogmo_rtdb_objname_t name; 00146 //!< (U) Name of the Object, doesn't need to be unique 00147 00148 kogmo_timestamp_t created_ts; 00149 //!< (D) Time of Object creation 00150 00151 kogmo_rtdb_objid_t created_proc; 00152 //!< (D) Process-ID of the Process, that created the Object 00153 00154 kogmo_timestamp_t lastmodified_ts; 00155 //!< (D) (unused so far) 00156 kogmo_rtdb_objid_t lastmodified_proc; 00157 //!< (D) (unused so far) 00158 00159 kogmo_timestamp_t deleted_ts; 00160 //!< (D) Time of Object deletion; metadata has to be kept until 00161 //!< the last Object dataset is beyond history limit 00162 kogmo_rtdb_objid_t deleted_proc; 00163 //!< (D) Process that deleted the Object (so far only the owner) 00164 00165 kogmo_rtdb_objid_t parent_oid; 00166 //!< (U) Object-ID of the Parent-Object within the Scene-Tree; 00167 //!< Could be 0 if unwanted. 00168 00169 kogmo_rtdb_objtype_t otype; 00170 //!< (U) Type of the Object; 00171 //!< Default: KOGMO_RTDB_DEFAULT_TYPE 00172 00173 kogmo_rtdb_objsize_t size_max; 00174 //!< (U) Maximum Objectdata-Size that can be used in a commit 00175 00176 float history_interval; 00177 //!< (U) Time Interval in Seconds the History of Object-Data should 00178 //!< be kept; 00179 //!< 0: use Default 00180 00181 // Ugly, but for compatibility: 00182 #define min_cycletime avg_cycletime 00183 // NEW! Reused, was avg_cycletime 00184 float min_cycletime; 00185 //!< (U) Minimum time between Object-Changes (commits). 00186 //!< Bad things might happen if exceeded (so far, the history will be 00187 //!< shorter). Can be enforced by setting the cycle_watch flag; 00188 //!< \n Note 1: If min_cycletime > max_cycletime will be automatically swapped internaly when used, 00189 //!< but the kogmo_rtdb_obj_info_t will not be touched so far. 00190 //!< \n Note 2: The meaning of max_cycletime / min_cycletime are swapped since 00191 //!< the very first release, because I mixed up max_cycletime and max_cyclefreq. 00192 //!< \n 0: use Default 00193 float max_cycletime; 00194 //!< (U) Maximum time between Object-Changes (commits); 00195 //!< If exceeded, the latest data is regarded stale. 00196 //!< If withhold_stale is set, readers will not get this stale data. 00197 //!< See also min_cycletime (=avg_cycletime) for notes. 00198 00199 struct 00200 { 00201 uint32_t read_deny : 1; 00202 //!< (U) 1: Object Data only readable by own handle; 00203 //!< 0: default: public readable 00204 uint32_t write_allow : 1; 00205 //!< (U) 1: Object writable by others, they can update and delete the object; 00206 //!< 0: default: not public writable 00207 uint32_t keep_alloc : 1; 00208 //!< (U) 1: Allocated Memory for Object will be kept after deletion, 00209 //!< and will be re-used for the next new object of the same type 00210 //!< created by the same process. 00211 //!< Warning: This is only a hint to the rtdb, don't assume that 00212 //!< you'll get the same ids and pointers. Just assume that you 00213 //!< get a totally new object, but expect less time for creation. 00214 //!< 0: default: free all memory after deletion 00215 uint32_t unique : 1; 00216 //!< (U) 1: Object must be unique - a second object with the same name and 00217 //!< object type (otype) will be refused; 00218 //!< 0: default: not public writable 00219 uint32_t cycle_watch : 1; 00220 //!< (U) 1: Object Data Updates cannot occur at a higher rate than max_cycletime, 00221 //1< The committing process will be delayed if it tries; 00222 //!< 0: default: do not watch and enforce the maximum update rate; 00223 uint32_t persistent : 1; 00224 //!< (U) 1: Object will remain in RTDB even if the creating process dies. 00225 //!< It's recommended to also set write_allow. 00226 //!< 0: default: not persistent 00227 uint32_t parent_delete : 1; 00228 //!< (U) 1: Object will be deleted if the parent object is deleted. 00229 //!< It's useful in combination with persistent and write_allow. 00230 //!< 0: default: survive parent. 00231 uint32_t no_notifies : 1; 00232 //!< (U) 1: Do not send notifies on object writes. 00233 //!< This makes commiting even faster and is only useful for very high frequent 00234 //!< real-time processes. Other processes that use kogmo_rtdb_obj_readdata_waitnext() 00235 //!< on this object, will automatically poll for changes (with about 0.1*avg_cycletime). 00236 //!< So by concept you get a new value every time you use kogmo_rtdb_obj_readdata(). 00237 //!< 0: default: send notifies. 00238 uint32_t immediately_delete : 1; 00239 //!< (U) 1: Object will be deleted immediate. Use this only for huge rawdata objects. 00240 //!< 0: default: delete after 0.25-0.5 seconds, so an old version of this objects can 00241 //!< be used for error recovery. 00242 uint32_t withhold_stale : 1; 00243 //!< (U) 1: If the age of the latest object data is below the specified max_cycletime, 00244 // a read request for the latest date will fail. 00245 //!< 0: default: a read request always gives out data, even if it's stale. 00246 //!< be used for error recovery. 00247 } flags; 00248 00249 int32_t history_size; 00250 //!< (I) Current calculated amount history slots 00251 int32_t history_slot; 00252 //!< (I) Latest history slot 00253 kogmo_rtdb_objsize_t buffer_idx; 00254 //!< (I) Pointer to Object-Data within the Heap 00255 00256 } kogmo_rtdb_obj_info_t; 00257 00258 00259 /*@}*/ 00260 00261 00262 00263 00264 /*! \defgroup kogmo_rtdb_slot C-Functions for direct History Data Slot Access 00265 * \brief These Types are used as Parameters for some specializes Calls to the Database-API. 00266 */ 00267 /*@{*/ 00268 00269 00270 /*! \brief Specification of a certain history slot of an object for fast access. 00271 */ 00272 00273 typedef PACKED_struct 00274 { 00275 int32_t state; // reserved 00276 kogmo_rtdb_objid_t oid; 00277 kogmo_timestamp_t committed_ts; 00278 int32_t object_slot; 00279 int32_t history_slot; 00280 int32_t reserved0; 00281 int32_t reserved1; 00282 } kogmo_rtdb_obj_slot_t; 00283 00284 00285 /*@}*/ 00286 00287 00288 00289 00290 00291 00292 /*! \addtogroup kogmo_rtdb_conn 00293 */ 00294 /*@{*/ 00295 00296 /*! \brief Data Block for requesting a Database-Connection 00297 * This is used only once for establishing the Database Connection. 00298 * By using a struct, we can add more fields later. 00299 */ 00300 00301 typedef struct 00302 { 00303 _const char *procname; 00304 //!< choosen name for the process that connects to the database; 00305 //!< example: a2_roadtracker (should begin with subproject number) 00306 float cycletime; 00307 //!< your internal cycle time (0 for system default); 00308 //!< you must signal your vitality every cycle with kogmo_rtdb_cycle_done(); 00309 //!< example: 0.033 seconds for a video-process with 30 frames/s 00310 uint32_t flags; 00311 //!< normally 0 00312 _const char *dbhost; 00313 //!< set to NULL or "" for default local database; 00314 //!< (for future extendability, more local databases, network, etc.) 00315 uint32_t version; 00316 //!< your version identification (SVN revision or similar) 00317 } kogmo_rtdb_connect_info_t; 00318 00319 00320 /*! \brief Flags to modify RTDB Connections 00321 * These have to be ORed and set to kogmo_rtdb_connect_info_t.flags 00322 * or as argument to RTDBConn (). 00323 * Please do not try other values! 00324 */ 00325 00326 #define KOGMO_RTDB_CONNECT_FLAGS_NOHANDLERS 0x0001 00327 //!< Normally, every process using the rtdb-libraries, will get signal-handlers 00328 //!< to make sure that kogmo_rtdb_disconnect() is called at programm termination. 00329 //!< By setting this flag you can prevent this, but PLEASE call kogmo_rtdb_disconnect(), 00330 //!< otherwise the programms object won't get removed immediately. 00331 #define KOGMO_RTDB_CONNECT_FLAGS_TRYNOWAIT 0x0004 00332 //!< Normally, if there's no database to connect to, 00333 //!< kogmo_rtdb_connect() just waits until it finds one. 00334 //!< This way, you can start your applications before the 00335 //!< database. 00336 //!< By setting this flag kogmo_rtdb_connect() returns 00337 //!< without waiting, if there's no database. 00338 //!< Depending on KOGMO_RTDB_CONNECT_FLAGS_LIVEONERR 00339 //!< your application terminates or gets a negative return code. 00340 #define KOGMO_RTDB_CONNECT_FLAGS_SILENT 0x0008 00341 //!< Do not output error messages, useful in combination with 00342 //!< TRYNOWAIT and LIVEONERR. 00343 #define KOGMO_RTDB_CONNECT_FLAGS_LIVEONERR 0x0010 00344 //!< Normally, if there are problems connecting to 00345 //!< the database, your application terminates. 00346 //!< By setting this flag your application just 00347 //!< gets a negative return code for kogmo_rtdb_connect(), 00348 //!< an lives on. 00349 #define KOGMO_RTDB_CONNECT_FLAGS_IMMEDIATELYDELETE 0x0020 00350 //!< If this process dies, immediately delete all its objects. 00351 //!< Please use this only for processes that need much memory for 00352 //!< raw data acquisition (and for the player). 00353 #define KOGMO_RTDB_CONNECT_FLAGS_REALTIME 0x0100 00354 //!< (internal, ask matthias.goebl*goebl.net before use) 00355 00356 /*@}*/ 00357 00358 00359 #ifndef KOGMO_RTDB_DONT_DEFINE_HANDLE 00360 typedef struct { 00361 char dummy[80]; 00362 } kogmo_rtdb_handle_t; 00363 #endif 00364 00365 00366 00367 00368 #ifdef __cplusplus 00369 }; /* extern "C" */ 00370 }; /* namespace KogniMobil */ 00371 #endif 00372 00373 #endif /* KOGMO_RTDB_TYPES_H */