[librsvg: 9/10] rsvg_handle_get_intrinsic_dimensions(): Move the out-of-order panic to the toplevel code



commit a666e088c7f165a37c36c72d8f10efa2332baf70
Author: Federico Mena Quintero <federico gnome org>
Date:   Tue Jul 23 16:22:17 2019 -0500

    rsvg_handle_get_intrinsic_dimensions(): Move the out-of-order panic to the toplevel code
    
    And start documenting the API ordering requirements.

 librsvg/rsvg-handle.c       | 35 +++++++++++++++++++++++++++++++++++
 rsvg_internals/src/c_api.rs | 10 ++++++----
 2 files changed, 41 insertions(+), 4 deletions(-)
---
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c
index 2c6908ad..db1032dc 100644
--- a/librsvg/rsvg-handle.c
+++ b/librsvg/rsvg-handle.c
@@ -172,6 +172,38 @@
  * control the size at which the SVG will be rendered.  It will just be rendered
  * at the size which rsvg_handle_get_dimensions() would return, which depends on
  * the dimensions that librsvg is able to compute from the SVG data.
+ *
+ * # API ordering
+ *
+ * Due to the way the librsvg API evolved over time, an #RsvgHandle object is available
+ * for use as soon as it is constructed.  However, not all of its methods can be
+ * called at any time.  For example, an #RsvgHandle just constructed with rsvg_handle_new()
+ * is not loaded yet, and it does not make sense to call rsvg_handle_get_dimensions() on it
+ * just at that point.
+ *
+ * The documentation for the available methods in #RsvgHandle may mention that a particular
+ * method is only callable on a "fully loaded handle".  This means either:
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     The handle was loaded with rsvg_handle_write() and rsvg_handle_close(), and
+ *     those functions returned no errors.
+ *   </listitem>
+ *   <listitem>
+ *     The handle was loaded with rsvg_handle_read_stream_sync() and that function
+ *     returned no errors.
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * Before librsvg 2.46, the library did not fully verify that a handle was in a
+ * fully loaded state for the methods that require it.  To preserve
+ * compatibility with old code which inadvertently called the API without
+ * checking for errors, or which called some methods outside of the expected
+ * order, librsvg will just emit a g_critical() message in those cases.
+ *
+ * New methods introduced in librsvg 2.46 and later will check for the correct
+ * ordering, and panic if they are called out of order.  Please check all calls for
+ * errors!
  */
 
 /***** Begin documentation for RsvgHandle properties *****/
@@ -1064,6 +1096,9 @@ rsvg_handle_set_size_callback (RsvgHandle *handle,
  * <svg xmlns="http://www.w3.org/2000/svg"; width="210mm" height="297mm">
  * ]|
  *
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <link href="#API-ordering">API ordering</link> for details.
+ *
  * Since: 2.46
  */
 void
diff --git a/rsvg_internals/src/c_api.rs b/rsvg_internals/src/c_api.rs
index cdacbb9c..ee496a2f 100644
--- a/rsvg_internals/src/c_api.rs
+++ b/rsvg_internals/src/c_api.rs
@@ -711,9 +711,9 @@ impl CHandle {
         handle.get_geometry_for_element(id, viewport, self.dpi.get(), self.is_testing.get())
     }
 
-    fn get_intrinsic_dimensions(&self) -> IntrinsicDimensions {
-        let handle = self.get_handle_ref().unwrap();
-        handle.get_intrinsic_dimensions()
+    fn get_intrinsic_dimensions(&self) -> Result<IntrinsicDimensions, RenderingError> {
+        let handle = self.get_handle_ref()?;
+        Ok(handle.get_intrinsic_dimensions())
     }
 
     fn set_testing(&self, is_testing: bool) {
@@ -1236,7 +1236,9 @@ pub unsafe extern "C" fn rsvg_rust_handle_get_intrinsic_dimensions(
 ) {
     let rhandle = get_rust_handle(handle);
 
-    let d = rhandle.get_intrinsic_dimensions();
+    let d = rhandle
+        .get_intrinsic_dimensions()
+        .unwrap_or_else(|_| panic!("API called out of order"));
 
     let w = d.width.map(|l| l.to_length());
     let h = d.height.map(|l| l.to_length());


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]