Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members  

CosClockService.idl

Go to the documentation of this file.
00001  
00002 
00003 //Enhanced View of Time, v1.0 - OMG IDL Summary File
00004 //Object Management Group, Inc.
00005 //
00006 //Copyright 1999, Objective Interface Systems, Inc.
00007 //Copyright 2001, Object Management Group, Inc.
00008 
00009 //The companies listed above have granted to the Object Management Group, Inc. 
00010 //(OMG) a nonexclusive, royalty-free, paid up, worldwide license to copy and 
00011 //distribute this document and to modify this document and distribute copies of 
00012 //the modified version. Each of the copyright holders listed above has agreed 
00013 //that no person shall be deemed to have infringed the copyright in the included 
00014 //material of any such copyright holder by reason of having used the 
00015 //specification set forth herein or having conformed any computer software to 
00016 //the specification. 
00017 //
00018 //This file contains OMG IDL from the Enhanced View of Time, v1.0 specification.
00019 //OMG regularly publishes a summary file that contains all the "code" parts of 
00020 //an OMG formal document. Every formal document line that is IDL, PIDL, or 
00021 //language code is included in the summary file. The reason for such a listing 
00022 //is to give readers an electronic version of the "code" so that they can 
00023 //extract pieces of it. Readers might want to test an example, include it in 
00024 //their own code, or use it for documentation purposes. Having the code lines 
00025 //available electronically means there is less likelihood of a transcription 
00026 //error. 
00027 
00028 
00029 //File: CosClockService.idl
00030 #ifndef _CosClockService_IDL_
00031 #define _CosClockService_IDL_
00032 
00033 // This module comprises the COS Clock service
00034 
00035 #include <TimeBase.idl>
00036 #include <CosPropertyService.idl>
00037 
00038 #pragma prefix "omg.org"
00039 module CosClockService 
00040 {
00041 
00042         interface Clock;
00043     
00044         module ClockProperty 
00045         {// the minimum set of properties to be supported for a clock
00046             typedef unsigned long Resolution; // units = nanoseconds
00047          typedef short Precision; // ceiling of log_2(seconds signified by least
00048                          // significant bit of time readout)
00049          typedef unsigned short Width; // no. of bits in readout - usually <= 64
00050          typedef string Stability_Description;
00051 
00052          typedef short Coordination;
00053          const Coordination Uncoordinated = 0; // only static characterization
00054                           // is available
00055          const Coordination Coordinated   = 1; // measured against another
00056                            // source
00057          const Coordination Faulty        = 2; // e.g., there is a bit stuck
00058 
00059          // the following are only applicable for coordinated clocks
00060          struct Offset
00061          {
00062               long long measured;   // units = 100 nanoseconds
00063               long long deliberate; // units = 100 nanoseconds
00064          };
00065 
00066          typedef short Measurement;
00067          const Measurement Not_Determined = 0; // has not been measured
00068          const Measurement Discontinuous  = 1; // e.g., one clock is paused
00069          const Measurement Available      = 2; // has been measured
00070 
00071          typedef float Hz;
00072          struct Skew 
00073          {
00074               Measurement available;
00075               Hz measured;   // only meaningful if available = Available - in Hz
00076               Hz deliberate; // in Hz
00077          };
00078          typedef float HzPerSec;
00079          struct Drift 
00080          {
00081               Measurement available;
00082               HzPerSec measured;  // meaningful if available = Available
00083                                   // in Hz/sec
00084               HzPerSec deliberate; // in Hz/sec
00085          };
00086            
00087          typedef short TimeScale;
00088          const TimeScale Unknown  = -1;
00089          const TimeScale TAI      = 0;  // International Atomic Time
00090          const TimeScale UT0      = 1;  // diurnal day
00091          const TimeScale UT1      = 2;  // + polar wander
00092          const TimeScale UTC      = 3;  // TAI + leap seconds
00093          const TimeScale TT       = 4;  // terrestrial time
00094          const TimeScale TDB      = 5;  // Barycentric Dynamical Time
00095          const TimeScale TCG      = 6;  // Geocentric Coordinate Time
00096          const TimeScale TCB      = 7;  // Barycentric Coordinate Time
00097          const TimeScale Sidereal = 8;  // hour angle of vernal equinox
00098          const TimeScale _Local    = 9;  // UTC + time zone
00099          const TimeScale GPS      = 10; // Global Positioning System
00100          const TimeScale Other    = 0x7fff; // e.g. mission
00101 
00102          typedef short Stratum; 
00103          const Stratum unspecified = 0;
00104          const Stratum primary_reference = 1;
00105          const Stratum secondary_reference_base = 2;
00106        
00107          typedef Clock CoordinationSource; // what clock is coordinating with
00108          typedef string Comments;
00109         };
00110    
00111          exception TimeUnavailable {};
00112 
00113          // the basic clock interface
00114          interface Clock // a source of time readings
00115          {
00116          readonly attribute CosPropertyService::PropertySet properties;
00117          TimeBase::TimeT current_time() raises(TimeUnavailable);
00118             //  getRaises(TimeUnavailable);
00119         };
00120    
00121          enum TimeComparison
00122         {
00123                 TCEqualTo,
00124                 TCLessThan,
00125                 TCGreaterThan,
00126                 TCIndeterminate
00127         };
00128 
00129         enum ComparisonType
00130         {
00131                 IntervalC,      
00132                 MidC        
00133         };
00134    
00135          enum OverlapType
00136         {
00137                 OTContainer,
00138                 OTContained,
00139                 OTOverlap,
00140                 OTNoOverlap
00141         };
00142     
00143         valuetype TimeSpan;
00144     
00145         // replaces UTO from CosTime
00146         valuetype UTC
00147         {
00148          factory init(in TimeBase::UtcT from);
00149          factory compose(in TimeBase::TimeT time,
00150                 in unsigned long   inacclo,
00151                 in unsigned short  inacchi,
00152                 in TimeBase::TdfT  tdf);
00153         public TimeBase::TimeT time;
00154           public unsigned long   inacclo;
00155           public unsigned short  inacchi;
00156           public TimeBase::TdfT  tdf;
00157 
00158           TimeBase::InaccuracyT  inaccuracy();
00159           TimeBase::UtcT         utc_time();
00160 
00161           TimeComparison compare_time(in ComparisonType comparison_type,
00162                         in UTC with_utc);
00163           TimeSpan interval();
00164         };
00165    
00166         // replaces TIO from CosTime
00167         valuetype TimeSpan 
00168         {
00169           factory init   (in TimeBase::IntervalT from);
00170           factory compose(in TimeBase::TimeT lower_bound, 
00171                                 in TimeBase::TimeT upper_bound);
00172         
00173           public TimeBase::TimeT lower_bound;
00174           public TimeBase::TimeT upper_bound;
00175           TimeBase::IntervalT time_interval();
00176           OverlapType spans (
00177                 in  UTC      time,
00178                 out TimeSpan overlap
00179                 );
00180           OverlapType overlaps (
00181                 in TimeSpan  other,
00182                 out TimeSpan overlap
00183                 );
00184           UTC time ();
00185         };
00186    
00187         // replaces TimeService from CosTime
00188         interface UtcTimeService : Clock
00189         {
00190           UTC universal_time() raises(TimeUnavailable);
00191           UTC secure_universal_time() raises(TimeUnavailable);
00192           UTC absolute_time(in UTC with_offset) raises(TimeUnavailable);
00193     };
00194 
00195         // alternative to Trader service (e.g., for embedded systems)
00196         interface ClockCatalog 
00197         {
00198        struct ClockEntry 
00199        {
00200                 Clock         subject;
00201                 string        name;
00202        };
00203        typedef sequence<ClockEntry> ClockEntries;
00204        exception UnknownEntry {};
00205 
00206        ClockEntry get_entry(in string with_name) raises (UnknownEntry);
00207        ClockEntries available_entries();
00208        void register(in ClockEntry entry);
00209        void delete_entry(in string with_name) raises (UnknownEntry);
00210         };
00211 
00212         // a controllable clock
00213         interface ControlledClock: Clock
00214         {
00215        exception NotSupported {};
00216        void set(in TimeBase::TimeT to)  raises (NotSupported);
00217        void set_rate(in float ratio)    raises (NotSupported);
00218        void pause()                       raises (NotSupported);
00219        void resume()                    raises (NotSupported);
00220        void terminate()                 raises (NotSupported);
00221         }; 
00222 
00223         // useful for building user synchronized clocks
00224         interface SynchronizeBase : Clock
00225         {
00226        struct SyncReading 
00227        {
00228                 TimeBase::TimeT local_send;
00229                 TimeBase::TimeT local_receive;
00230                 TimeBase::TimeT remote_reading;
00231         };
00232         
00233                 SyncReading synchronize_poll(in Clock with_master);
00234         };
00235    
00236         interface SynchronizedClock;
00237    
00238         exception UnableToSynchronize
00239         { 
00240        TimeBase::InaccuracyT minimum_error; 
00241         };
00242 
00243         // allows definition of a new clock that uses the underlying hardware source
00244         // of the existing clock but adjusts to synchronize with a master clock
00245         interface Synchronizable : SynchronizeBase
00246         {
00247        const TimeBase::TimeT Forever = 0x7FFFFFFF;
00248 
00249        SynchronizedClock new_slave
00250                 (in Clock                  to_master,
00251                 in TimeBase::InaccuracyT   to_within,
00252                              // synchronization envelope
00253                 in short                   retry_limit,
00254                             // if unable to attain accuracy
00255                 in TimeBase::TimeT         minimum_delay_between_syncs,
00256                            // limits network traffic,
00257                            // Forever precludes auto resync
00258                 in CosPropertyService::Properties properties
00259                           // if null list, then inherit
00260                           // properties of self
00261           ) raises (UnableToSynchronize);
00262    };
00263    
00264         // able to explicitly control synchronization
00265         interface SynchronizedClock : Clock 
00266         {
00267        void resynch_now() raises (UnableToSynchronize);
00268         };
00269 
00270         module PeriodicExecution
00271         {
00272 
00273       // (conceptually abstract) base for objects that can be invoked periodically
00274       interface Periodic 
00275       {
00276          boolean do_work(in any params);
00277          // return FALSE terminates periodic execution
00278       };
00279    
00280       // control object for periodic execution
00281        interface Controller
00282        {
00283                 exception TimePast {};
00284                 void start
00285              (in TimeBase::TimeT period,
00286                in TimeBase::TimeT with_offset,
00287                in unsigned long   execution_limit, // 0 = no limit
00288                in any             params);
00289            void start_at
00290            (in TimeBase::TimeT period,
00291               in TimeBase::TimeT at_time,
00292               in unsigned long   execution_limit, // 0 = no limit
00293               in any             params) raises (TimePast);
00294            void pause();
00295            void resume();
00296            void resume_at(in TimeBase::TimeT at_time) raises(TimePast);
00297            void terminate();
00298            unsigned long executions();
00299         };
00300 
00301         // factory clock for periodic execution
00302         interface Executor : Clock
00303         {
00304               Controller enable_periodic_execution(in Periodic on);
00305        };
00306         };
00307     
00308 };
00309 #endif // _CosClockService_IDL_