Binex (#277)

* Improve API (Meta, ..) * Small performance improvement * slighly more efficient Meta decoding --------- Signed-off-by: Guillaume W. Bres <[email protected]>
georust · Nov 3, 2024 · 11bbc4f · 11bbc4f
1 parent 3a68b28
commit 11bbc4f
Show file tree

Hide file tree

Showing 11 changed files with 508 additions and 463 deletions.
diff --git a/binex/README.md b/binex/README.md
@@ -45,14 +45,21 @@ loop {
             // fully interprated element
         },
         Some(Ok(StreamElement::ClosedSource(element))) => {
+            // grab content you will need to interpate
+            let closed_meta = element.closed_meta; 
+            let open_meta = closed_meta.open_meta;
+
             // verify this is your organization
-            if element.meta.provider == Provider::JPL {
+            if closed_meta.provider == Provider::JPL {
+
                 // grab fields that you probably need to decode
-                let mid = element.meta.mid;
-                let mlen = element.meta.mlen;
-                let big_endian = element.meta.big_endian;
-                let is_reversed = element.meta.reversed;
-                let enhanced_crc = element.meta.enhanced_crc;
+                let big_endian = open_meta.big_endian;
+                let is_reversed = open_meta.reversed;
+                let enhanced_crc = open_meta.enhanced_crc;
+
+                let mid = closed_meta.mid; // message ID
+                let mlen = closed_meta.mlen; // total message length
+                let chunk_size = closed_meta.size; // chunk length
 
                 // now, proceed to interpretation of this element,
                 // using undisclosed method

diff --git a/binex/benches/decoding.rs b/binex/benches/decoding.rs
@@ -1,12 +1,16 @@
 use binex::prelude::{
-    EphemerisFrame, Epoch, Message, MonumentGeoMetadata, MonumentGeoRecord, Record, TimeResolution,
+    EphemerisFrame, Epoch, Message, Meta, MonumentGeoMetadata, MonumentGeoRecord, Record,
+    TimeResolution,
 };
 use criterion::{black_box, criterion_group, criterion_main, Criterion};
 
 #[allow(unused_must_use)]
 pub fn criterion_benchmark(c: &mut Criterion) {
+    let mut meta = Meta::default();
+    meta.big_endian = true;
+
     let t0 = Epoch::from_gpst_seconds(10.0);
-    let meta = MonumentGeoMetadata::RNX2BIN;
+    let geo_meta = MonumentGeoMetadata::RNX2BIN;
 
     let mut record = MonumentGeoRecord::default()
         .with_comment("This is a test")
@@ -15,13 +19,13 @@ pub fn criterion_benchmark(c: &mut Criterion) {
         .with_user_id("Test");
 
     record.epoch = t0;
-    record.meta = meta;
+    record.meta = geo_meta;
 
     let record = Record::new_monument_geo(record);
-    let msg = Message::new(true, TimeResolution::QuarterSecond, false, false, record);
+    let msg = Message::new(meta, TimeResolution::QuarterSecond, record);
 
     let mut buf = [0; 256];
-    msg.encode(&mut buf).unwrap();
+    msg.encode(&mut buf, 256).unwrap();
 
     c.bench_function("decoding-00", |b| {
         b.iter(|| {
@@ -30,10 +34,10 @@ pub fn criterion_benchmark(c: &mut Criterion) {
     });
 
     let record = Record::new_ephemeris_frame(EphemerisFrame::GPSRaw(Default::default()));
-    let msg = Message::new(true, TimeResolution::QuarterSecond, false, false, record);
+    let msg = Message::new(meta, TimeResolution::QuarterSecond, record);
 
     let mut buf = [0; 256];
-    msg.encode(&mut buf).unwrap();
+    msg.encode(&mut buf, 256).unwrap();
 
     c.bench_function("decoding-01-00", |b| {
         b.iter(|| {
@@ -42,10 +46,10 @@ pub fn criterion_benchmark(c: &mut Criterion) {
     });
 
     let record = Record::new_ephemeris_frame(EphemerisFrame::GPS(Default::default()));
-    let msg = Message::new(true, TimeResolution::QuarterSecond, false, false, record);
+    let msg = Message::new(meta, TimeResolution::QuarterSecond, record);
 
     let mut buf = [0; 256];
-    msg.encode(&mut buf).unwrap();
+    msg.encode(&mut buf, 256).unwrap();
 
     c.bench_function("decoding-01-01", |b| {
         b.iter(|| {

diff --git a/binex/benches/encoding.rs b/binex/benches/encoding.rs
@@ -1,13 +1,18 @@
 use binex::prelude::{
-    EphemerisFrame, Epoch, Message, MonumentGeoMetadata, MonumentGeoRecord, Record, TimeResolution,
+    EphemerisFrame, Epoch, Message, Meta, MonumentGeoMetadata, MonumentGeoRecord, Record,
+    TimeResolution,
 };
 use criterion::{black_box, criterion_group, criterion_main, Criterion};
 
 #[allow(unused_must_use)]
 pub fn criterion_benchmark(c: &mut Criterion) {
     let mut buf = [0; 256];
+
+    let mut meta = Meta::default();
+    meta.big_endian = true;
+
     let t0 = Epoch::from_gpst_seconds(10.0);
-    let meta = MonumentGeoMetadata::RNX2BIN;
+    let geo_meta = MonumentGeoMetadata::RNX2BIN;
 
     let mut record = MonumentGeoRecord::default()
         .with_comment("This is a test")
@@ -16,32 +21,32 @@ pub fn criterion_benchmark(c: &mut Criterion) {
         .with_user_id("Test");
 
     record.epoch = t0;
-    record.meta = meta;
+    record.meta = geo_meta;
 
     let record = Record::new_monument_geo(record);
-    let msg = Message::new(true, TimeResolution::QuarterSecond, false, false, record);
+    let msg = Message::new(meta, TimeResolution::QuarterSecond, record);
 
     c.bench_function("encoding-00", |b| {
         b.iter(|| {
-            black_box(msg.encode(&mut buf).unwrap());
+            black_box(msg.encode(&mut buf, 256).unwrap());
         })
     });
 
     let record = Record::new_ephemeris_frame(EphemerisFrame::GPSRaw(Default::default()));
-    let msg = Message::new(true, TimeResolution::QuarterSecond, false, false, record);
+    let msg = Message::new(meta, TimeResolution::QuarterSecond, record);
 
     c.bench_function("encoding-01-00", |b| {
         b.iter(|| {
-            black_box(msg.encode(&mut buf).unwrap());
+            black_box(msg.encode(&mut buf, 256).unwrap());
         })
     });
 
     let record = Record::new_ephemeris_frame(EphemerisFrame::GPS(Default::default()));
-    let msg = Message::new(true, TimeResolution::QuarterSecond, false, false, record);
+    let msg = Message::new(meta, TimeResolution::QuarterSecond, record);
 
     c.bench_function("encoding-01-01", |b| {
         b.iter(|| {
-            black_box(msg.encode(&mut buf).unwrap());
+            black_box(msg.encode(&mut buf, 256).unwrap());
         })
     });
 }

diff --git a/binex/src/constants.rs b/binex/src/constants.rs
diff --git a/binex/src/decoder.rs b/binex/src/decoder.rs
@@ -236,12 +236,12 @@ impl<'a, R: Read> Iterator for Decoder<'a, R> {
                             return Some(Err(Error::IncompleteMessage(mlen)));
                         }
                     },
-                    Error::ClosedSourceMessage(meta) => {
+                    Error::ClosedSourceMessage(closed_source) => {
                         // determine whether
                         // - this element is self sustained (ie., fully described by this meta)
                         // - the followup of previous elements
                         // - or the last element of a serie
-                        if self.rd_ptr + meta.mlen < 4096 {
+                        if self.rd_ptr + closed_source.size < 4096 {
                             // content is fully wrapped in buffer: expose as is
                             // self.past_element = Some(ClosedSourceElement {
                             //     provider: meta.provider,
@@ -253,7 +253,7 @@ impl<'a, R: Read> Iterator for Decoder<'a, R> {
                             // content is not fully wrapped up here;
                             // initiate or continue a serie of undisclosed element
                         }
-                        return Some(Err(Error::IncompleteMessage(meta.mlen)));
+                        return Some(Err(Error::IncompleteMessage(closed_source.size)));
                     },
                     Error::UnknownMessage => {
                         // panic!("unknown message\nrd_ptr={}\nbuf={:?}", self.rd_ptr, &self.buf[self.rd_ptr-1..self.rd_ptr+4]);

diff --git a/binex/src/lib.rs b/binex/src/lib.rs
@@ -8,14 +8,13 @@ mod decoder;
 mod message;
 mod stream;
 
-pub(crate) mod constants;
 pub(crate) mod utils;
 
 pub mod prelude {
     pub use crate::{
         decoder::Decoder,
         message::{
-            EphemerisFrame, GALEphemeris, GLOEphemeris, GPSEphemeris, GPSRaw, Message,
+            EphemerisFrame, GALEphemeris, GLOEphemeris, GPSEphemeris, GPSRaw, Message, Meta,
             MonumentGeoMetadata, MonumentGeoRecord, Record, SBASEphemeris, TimeResolution,
         },
         stream::{ClosedSourceElement, Provider, StreamElement},
@@ -25,22 +24,23 @@ pub mod prelude {
     pub use hifitime::Epoch;
 }
 
+use crate::message::Meta;
 use crate::stream::Provider;
 
 /// [ClosedSourceMeta] helps identify a closed source message we cannot interprate.
-#[derive(Debug)]
+#[derive(Debug, Copy, Clone)]
 pub struct ClosedSourceMeta {
-    // decoded MID (as is)
+    /// Message ID "as is"
     pub mid: u32,
-    /// decoded MLEN (as is)
+    /// Message length (total payload) "as is"
     pub mlen: usize,
-    /// Whether this item is reversed or not
-    pub reversed: bool,
-    /// Whether this item uses enhanced CRC or not
-    pub enhanced_crc: bool,
-    /// Whether this is big endian encoded or not
-    pub big_endian: bool,
-    /// [Provider] of this message. Only this organization may continue the decoding process.
+    /// Size of chunk.
+    /// This library is designed to support all open source messages that are short.
+    /// Yet a BINEX (prototype) message may span 2^27 bytes.
+    pub size: usize,
+    /// [Meta] data that follows the open source protocol.
+    pub open_meta: Meta,
+    /// [Provider] of this message. Only this organization may fully decode this message.
     pub provider: Provider,
     // payload offset in buffer
     offset: usize,