honeycomb_core::cmap

Struct CMap2

Source
pub struct CMap2<T: CoordsFloat> { /* private fields */ }
Expand description

Main map object.

Structure used to model 2D combinatorial map. The structure implements basic operations as well as higher level abstractions that are useful to write meshing applications.

Definition of the structure and its logic can be found in the user guide. This documentation focuses on the implementation and its API.

This structure only implements Clone if the utils feature is enabled.

§Fields

Fields are kept private in order to better define interfaces. The structure contains the following data:

  • an array-based representation of the beta functions
  • a storage structure for vertices making up the represented mesh
  • a generic storage manager for user-defined attributes

Note that:

  • we encode β0 as the inverse function of β1. This is extremely useful (read required) to implement correct and efficient i-cell computation. Additionally, while β0 can be accessed using the Self::beta method, we do not define the 0-sew / 0-unsew operations.
  • we chose a boundary-less representation of meshes (i.e. darts on the boundary are 2-free).

§Generics

  • T: CoordsFloat – Generic type for coordinates representation.

§Example

The following example goes over multiple operations on the mesh in order to demonstrate general usage of the structure and its methods.

CMAP2_EXAMPLE

Note that:

  • we create the map using its builder structure: CMapBuilder.
  • the map we operate on has no boundaries. In addition to the different operations realized at each step, we insert a few assertions to demonstrate the progressive changes applied to the structure.

use honeycomb_core::prelude::{CMap2, CMapBuilder, Orbit2, OrbitPolicy, Vertex2};

// build a triangle
let mut map: CMap2<f64> = CMapBuilder::default().n_darts(3).build().unwrap(); // three darts
map.one_link(1, 2); // beta1(1) = 2 & beta0(2) = 1
map.one_link(2, 3); // beta1(2) = 3 & beta0(3) = 2
map.one_link(3, 1); // beta1(3) = 1 & beta0(1) = 3
map.insert_vertex(1, (0.0, 0.0));
map.insert_vertex(2, (1.0, 0.0));
map.insert_vertex(3, (0.0, 1.0));

// we can go through the face using an orbit
let mut face = Orbit2::new(&map, OrbitPolicy::Face, 1);
assert_eq!(face.next(), Some(1));
assert_eq!(face.next(), Some(2));
assert_eq!(face.next(), Some(3));
assert_eq!(face.next(), None);

// build a second triangle
let first_added_dart_id = map.add_free_darts(3);
assert_eq!(first_added_dart_id, 4);
map.one_link(4, 5);
map.one_link(5, 6);
map.one_link(6, 4);
map.insert_vertex(4, (0.0, 2.0));
map.insert_vertex(5, (2.0, 0.0));
map.insert_vertex(6, (1.0, 1.0));

// there should be two faces now
let faces = map.fetch_faces();
assert_eq!(&faces.identifiers, &[1, 4]);

// sew both triangles
map.two_sew(2, 4);

// there are 5 edges now, making up a square & its diagonal
let edges = map.fetch_edges();
assert_eq!(&edges.identifiers, &[1, 2, 3, 5, 6]);

// adjust bottom-right & top-left vertex position
// the returned values were the average of the sewn vertices
assert_eq!(
    map.replace_vertex(2, Vertex2::from((1.0, 0.0))),
    Some(Vertex2(1.5, 0.0))
);
assert_eq!(
    map.replace_vertex(3, Vertex2::from((0.0, 1.0))),
    Some(Vertex2(0.0, 1.5))
);

// separate the diagonal from the rest
map.one_unsew(1);
map.one_unsew(2);
map.one_unsew(6);
map.one_unsew(4);
// break up & remove the diagonal
map.two_unsew(2); // this makes dart 2 and 4 free
map.remove_free_dart(2);
map.remove_free_dart(4);
// sew the square back up
map.one_sew(1, 5);
map.one_sew(6, 3);

// there's only the square face left
let faces = map.fetch_faces();
assert_eq!(&faces.identifiers, &[1]);
// we can check the vertices
let vertices = map.fetch_vertices();
let mut value_iterator = vertices.identifiers.iter().map(|vertex_id| map.vertex(*vertex_id).unwrap());
assert_eq!(value_iterator.next(), Some(Vertex2::from((0.0, 0.0)))); // vertex ID 1
assert_eq!(value_iterator.next(), Some(Vertex2::from((0.0, 1.0)))); // vertex ID 3
assert_eq!(value_iterator.next(), Some(Vertex2::from((1.0, 0.0)))); // vertex ID 5
assert_eq!(value_iterator.next(), Some(Vertex2::from((1.0, 1.0)))); // vertex ID 6

Implementations§

Source§

impl<T: CoordsFloat> CMap2<T>

Dart-related methods

Source

pub fn n_darts(&self) -> usize

Return information about the current number of darts.

Source

pub fn n_unused_darts(&self) -> usize

Return information about the current number of unused darts.

Source

pub fn add_free_dart(&mut self) -> DartIdType

Add a new free dart to the combinatorial map.

The dart is i-free for all i and is pushed to the list of existing darts, effectively making its identifier equal to the total number of darts (post-push).

§Return

Return the ID of the created dart to allow for direct operations.

Source

pub fn add_free_darts(&mut self, n_darts: usize) -> DartIdType

Add multiple new free darts to the combinatorial map.

All darts are i-free for all i and are pushed to the end of the list of existing darts.

§Arguments
  • n_darts: usize – Number of darts to have.
§Return

Return the ID of the first created dart to allow for direct operations. Darts are positioned on range ID..ID+n_darts.

Source

pub fn insert_free_dart(&mut self) -> DartIdType

Insert a new free dart to the combinatorial map.

The dart is i-free for all i and may be inserted into an unused spot in the existing dart list. If no free spots exist, it will be pushed to the end of the list.

§Return

Return the ID of the created dart to allow for direct operations.

Source

pub fn remove_free_dart(&mut self, dart_id: DartIdType)

Remove a free dart from the combinatorial map.

The removed dart identifier is added to the list of free dart. This way of proceeding is necessary as the structure relies on darts indexing for encoding data, making reordering of any sort extremely costly.

By keeping track of free spots in the dart arrays, we can prevent too much memory waste, although at the cost of locality of reference.

§Arguments
  • dart_id: DartIdentifier – Identifier of the dart to remove.
§Panics

This method may panic if:

  • The dart is not i-free for all i.
  • The dart is already marked as unused (Refer to Self::remove_vertex documentation for a detailed breakdown of this choice).
Source§

impl<T: CoordsFloat> CMap2<T>

Beta-related methods

Source

pub fn beta<const I: u8>(&self, dart_id: DartIdType) -> DartIdType

Compute the value of the i-th beta function of a given dart.

§Arguments
  • dart_id: DartIdentifier – Identifier of a given dart.
§Generics
  • const I: u8 – Index of the beta function. I should be 0, 1 or 2 for a 2D map.
§Return

Return the identifier of the dart d such that d = βi(dart). If the returned value is the null dart (i.e. a dart ID equal to 0), this means that the dart is i-free.

§Panics

The method will panic if I is not 0, 1 or 2.

Source

pub fn beta_runtime(&self, i: u8, dart_id: DartIdType) -> DartIdType

Compute the value of the i-th beta function of a given dart.

§Arguments
  • dart_id: DartIdentifier – Identifier of a given dart.
  • i: u8 – Index of the beta function. i should be 0, 1 or 2 for a 2D map.
§Return

Return the identifier of the dart d such that d = βi(dart). If the returned value is the null dart (i.e. a dart ID equal to 0), this means that the dart is i-free.

§Panics

The method will panic if i is not 0, 1 or 2.

Source

pub fn is_i_free<const I: u8>(&self, dart_id: DartIdType) -> bool

Check if a given dart is i-free.

§Arguments
  • dart_id: DartIdentifier – Identifier of a given dart.
§Generics
  • const I: u8 – Index of the beta function. I should be 0, 1 or 2 for a 2D map.
§Return

Return a boolean indicating if the dart is i-free, i.e. βi(dart) = NULL_DART_ID.

§Panics

The function will panic if I is not 0, 1 or 2.

Source

pub fn is_free(&self, dart_id: DartIdType) -> bool

Check if a given dart is i-free, for all i.

§Arguments
  • dart_id: DartIdentifier – Identifier of a given dart.
§Return

Return a boolean indicating if the dart is 0-free, 1-free and 2-free.

Source§

impl<T: CoordsFloat> CMap2<T>

I-cell-related methods

Source

pub fn vertex_id(&self, dart_id: DartIdType) -> VertexIdType

Fetch vertex identifier associated to a given dart.

§Arguments
  • dart_id: DartIdentifier – Identifier of a given dart.
§Return

Return the identifier of the associated vertex.

§Note on cell identifiers

Cells identifiers are defined as the smallest identifier among the darts that make up the cell. This definition has three interesting properties:

  • A given cell ID can be computed from any dart of the cell, i.e. all darts have an associated cell ID.
  • Cell IDs are not affected by the order of traversal of the map.
  • Because the ID is computed in real time, there is no need to store cell IDs and ensure that the storage is consistent / up to date.

These properties come at the literal cost of the computation routine, which is:

  1. a BFS to compute a given orbit
  2. a minimum computation on the IDs composing the orbit
Source

pub fn edge_id(&self, dart_id: DartIdType) -> EdgeIdType

Fetch edge associated to a given dart.

§Arguments
  • dart_id: DartIdentifier – Identifier of a given dart.
§Return

Return the identifier of the associated edge.

§Note on cell identifiers

Cells identifiers are defined as the smallest identifier among the darts that make up the cell. This definition has three interesting properties:

  • A given cell ID can be computed from any dart of the cell, i.e. all darts have an associated cell ID.
  • Cell IDs are not affected by the order of traversal of the map.
  • Because the ID is computed in real time, there is no need to store cell IDs and ensure that the storage is consistent / up to date.

These properties come at the literal cost of the computation routine, which is:

  1. a BFS to compute a given orbit
  2. a minimum computation on the IDs composing the orbit
Source

pub fn face_id(&self, dart_id: DartIdType) -> FaceIdType

Fetch face associated to a given dart.

§Arguments
  • dart_id: DartIdentifier – Identifier of a given dart.
§Return

Return the identifier of the associated face.

§Note on cell identifiers

Cells identifiers are defined as the smallest identifier among the darts that make up the cell. This definition has three interesting properties:

  • A given cell ID can be computed from any dart of the cell, i.e. all darts have an associated cell ID.
  • Cell IDs are not affected by the order of traversal of the map.
  • Because the ID is computed in real time, there is no need to store cell IDs and ensure that the storage is consistent / up to date.

These properties come at the literal cost of the computation routine, which is:

  1. a BFS to compute a given orbit
  2. a minimum computation on the IDs composing the orbit
Source

pub fn i_cell<const I: u8>(&self, dart_id: DartIdType) -> Orbit2<'_, T>

Return an Orbit2 object that can be used to iterate over darts of an i-cell.

§Arguments
  • dart_id: DartIdentifier – Identifier of a given dart.
§Generics
  • const I: u8 – Dimension of the cell of interest. I should be 0 (vertex), 1 (edge) or 2 (face) for a 2D map.
§Return

Returns an Orbit2 that can be iterated upon to retrieve all dart member of the cell. Note that the dart passed as an argument is included as the first element of the returned orbit.

§Panics

The method will panic if I is not 0, 1 or 2.

Source

pub fn fetch_vertices(&self) -> VertexCollection<'_, T>

Return a collection of all the map’s vertices.

§Return

Return a VertexCollection object containing a list of vertex identifiers, whose validity is ensured through an implicit lifetime condition on the structure and original map.

Source

pub fn fetch_edges(&self) -> EdgeCollection<'_, T>

Return a collection of all the map’s edges.

§Return

Return an EdgeCollection object containing a list of edge identifiers, whose validity is ensured through an implicit lifetime condition on the structure and original map.

Source

pub fn fetch_faces(&self) -> FaceCollection<'_, T>

Return a collection of all the map’s faces.

§Return

Return a FaceCollection object containing a list of face identifiers, whose validity is ensured through an implicit lifetime condition on the structure and original map.

Source§

impl<T: CoordsFloat> CMap2<T>

Built-in vertex-related methods

Source

pub fn n_vertices(&self) -> usize

Return the current number of vertices.

Source

pub fn vertex(&self, vertex_id: VertexIdType) -> Option<Vertex2<T>>

Fetch vertex value associated to a given identifier.

§Arguments
  • vertex_id: VertexIdentifier – Identifier of the given vertex.
§Return

This method return a Option taking the following values:

  • Some(v: Vertex2) if there is a vertex associated to this ID.
  • None – otherwise
§Panics

The method may panic if:

  • the index lands out of bounds
  • the index cannot be converted to usize
Source

pub fn insert_vertex( &self, vertex_id: VertexIdType, vertex: impl Into<Vertex2<T>>, )

Insert a vertex in the combinatorial map.

This method can be interpreted as giving a value to the vertex of a specific ID. Vertices implicitly exist through topology, but their spatial representation is not automatically created at first.

§Arguments
  • vertex_id: VertexIdentifier – Vertex identifier to attribute a value to.
  • vertex: impl Into<Vertex2> – Value used to create a Vertex2 value.
§Panics

The method may panic if:

  • there is already a vertex associated to the specified index
  • the index lands out of bounds
  • the index cannot be converted to usize
Source

pub fn remove_vertex(&self, vertex_id: VertexIdType) -> Option<Vertex2<T>>

Remove a vertex from the combinatorial map.

§Arguments
  • vertex_id: VertexIdentifier – Identifier of the vertex to remove.
§Return

This method return a Option taking the following values:

  • Some(v: Vertex2) – The vertex was successfully removed & its value was returned
  • None – The vertex was not found in the internal storage
§Panics

The method may panic if:

  • the index lands out of bounds
  • the index cannot be converted to usize
Source

pub fn replace_vertex( &self, vertex_id: VertexIdType, vertex: impl Into<Vertex2<T>>, ) -> Option<Vertex2<T>>

Try to overwrite the given vertex with a new value.

§Arguments
  • vertex_id: VertexIdentifier – Identifier of the vertex to replace.
  • vertex: impl<Into<Vertex2>> – New value for the vertex.
§Return

This method return an Option taking the following values:

  • Some(v: Vertex2) – The vertex was successfully overwritten & its previous value was returned
  • None – The vertex was set, but no value were overwritten
§Panics

The method may panic if:

  • the index lands out of bounds
  • the index cannot be converted to usize
Source§

impl<T: CoordsFloat> CMap2<T>

Generic attribute-related methods

Source

pub fn set_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, val: A, )

Setter

Set the value of an attribute for a given index. This operation is not affected by the initial state of the edited entry.

§Arguments
  • index: A::IdentifierType – Cell index.
  • val: A – Attribute value.
§Generic
  • A: AttributeBind + AttributeUpdate – Attribute kind to edit.
§Panics

The method:

  • should panic if the index lands out of bounds
  • may panic if the index cannot be converted to usize
Source

pub fn insert_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, val: A, )

Setter

Insert an attribute value at a given undefined index. See the panics section information on behavior if the value is already defined.

§Arguments
  • index: A::IdentifierType – Cell index.
  • val: A – Attribute value.
§Generic
  • A: AttributeBind + AttributeUpdate – Attribute kind to edit.
§Panics

The method:

  • should panic if there is already a value associated to the specified index
  • should panic if the index lands out of bounds
  • may panic if the index cannot be converted to usize
Source

pub fn get_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, ) -> Option<A>

Getter

§Arguments
  • index: A::IdentifierType – Cell index.
§Generic
  • A: AttributeBind + AttributeUpdate – Attribute kind to edit.
§Return

The method should return:

  • Some(val: A) if there is an attribute associated with the specified index,
  • None if there is not.
§Panics

The method:

  • should panic if the index lands out of bounds
  • may panic if the index cannot be converted to usize
Source

pub fn replace_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, val: A, ) -> Option<A>

Setter

Replace the value of the attribute for a given index.

§Arguments
  • index: A::IdentifierType – Cell index.
  • val: A – Attribute value.
§Generic
  • A: AttributeBind + AttributeUpdate – Attribute kind to edit.
§Return

The method should return:

  • Some(val_old: A) if there was an attribute associated with the specified index,
  • None if there is not.

In both cases, the new value should be set to the one specified as argument.

§Panics

The method:

  • should panic if the index lands out of bounds
  • may panic if the index cannot be converted to usize
Source

pub fn remove_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, ) -> Option<A>

Remove an attribute value from the storage and return it

§Arguments
  • index: A::IdentifierType – Cell index.
§Generic
  • A: AttributeBind + AttributeUpdate – Attribute kind to edit.
§Return

The method should return:

  • Some(val: A) if there was an attribute associated with the specified index,
  • None if there is not.
§Panics

The method:

  • may panic if the index lands out of bounds
  • may panic if the index cannot be converted to usize
Source

pub fn remove_attribute_storage<A: AttributeBind + AttributeUpdate>(&mut self)

Remove an entire attribute storage from the map.

This method is useful when implementing routines that uses attributes to run; Those can then be removed before the final result is returned.

§Generic
  • A: AttributeBind + AttributeUpdate – Attribute stored by the fetched storage.
Source§

impl<T: CoordsFloat> CMap2<T>

Sew and unsew operations

Source

pub fn one_sew(&self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType)

1-sew operation.

This operation corresponds to coherently linking two darts via the β1 function. For a thorough explanation of this operation (and implied hypothesis & consequences), refer to the user guide.

§Arguments
  • lhs_dart_id: DartIdentifier – ID of the first dart to be linked.
  • rhs_dart_id: DartIdentifier – ID of the second dart to be linked.
  • policy: SewPolicy – Geometrical sewing policy to follow.

After the sewing operation, these darts will verify β1(lhs_dart) = rhs_dart. The β0 function is also updated.

§Panics

The method may panic if the two darts are not 1-sewable.

Source

pub fn atomically_one_sew( &self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, )

Atomically 1-sew two darts.

Source

pub fn two_sew(&self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType)

2-sew operation.

This operation corresponds to coherently linking two darts via the β2 function. For a thorough explanation of this operation (and implied hypothesis & consequences), refer to the user guide.

§Arguments
  • lhs_dart_id: DartIdentifier – ID of the first dart to be linked.
  • rhs_dart_id: DartIdentifier – ID of the second dart to be linked.
  • policy: SewPolicy – Geometrical sewing policy to follow.

After the sewing operation, these darts will verify β2(lhs_dart) = rhs_dart and β2(rhs_dart) = lhs_dart.

§Panics

The method may panic if:

  • the two darts are not 2-sewable,
  • the method cannot resolve orientation issues.
Source

pub fn atomically_two_sew( &self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, )

Atomically 2-sew two darts.

Source

pub fn one_unsew(&self, lhs_dart_id: DartIdType)

1-unsew operation.

This operation corresponds to coherently separating two darts linked via the β1 function. For a thorough explanation of this operation (and implied hypothesis & consequences), refer to the user guide.

§Arguments
  • lhs_dart_id: DartIdentifier – ID of the dart to separate.
  • policy: UnsewPolicy – Geometrical unsewing policy to follow.

Note that we do not need to take two darts as arguments since the second dart can be obtained through the β1 function. The β0 function is also updated.

§Panics

The method may panic if there’s a missing attribute at the splitting step. While the implementation could fall back to a simple unlink operation, it probably should have been called by the user, instead of unsew, in the first place.

Source

pub fn atomically_one_unsew(&self, lhs_dart_id: DartIdType)

Atomically 1-unsew two darts.

Source

pub fn two_unsew(&self, lhs_dart_id: DartIdType)

2-unsew operation.

This operation corresponds to coherently separating two darts linked via the β2 function. For a thorough explanation of this operation (and implied hypothesis & consequences), refer to the user guide.

§Arguments
  • lhs_dart_id: DartIdentifier – ID of the dart to separate.
  • policy: UnsewPolicy – Geometrical unsewing policy to follow.

Note that we do not need to take two darts as arguments since the second dart can be obtained through the β2 function.

§Panics

The method may panic if there’s a missing attribute at the splitting step. While the implementation could fall back to a simple unlink operation, it probably should have been called by the user, instead of unsew, in the first place.

Source

pub fn atomically_two_unsew(&self, lhs_dart_id: DartIdType)

Atomically 2-unsew two darts.

Source§

impl<T: CoordsFloat> CMap2<T>

Link and unlink operations

1-link operation.

This operation corresponds to linking two darts via the β1 function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s). The β0 function is also updated.

§Arguments
  • lhs_dart_id: DartIdentifier – ID of the first dart to be linked.
  • rhs_dart_id: DartIdentifier – ID of the second dart to be linked.
§Panics

This method may panic if lhs_dart_id isn’t 1-free or rhs_dart_id isn’t 0-free.

2-link operation.

This operation corresponds to linking two darts via the β2 function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s).

§Arguments
  • lhs_dart_id: DartIdentifier – ID of the first dart to be linked.
  • rhs_dart_id: DartIdentifier – ID of the second dart to be linked.
§Panics

This method may panic if one of lhs_dart_id or rhs_dart_id isn’t 2-free.

1-unlink operation.

This operation corresponds to unlinking two darts that are linked via the β1 function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s). The β0 function is also updated.

§Arguments
  • lhs_dart_id: DartIdentifier – ID of the dart to unlink.
§Panics

This method may panic if one of lhs_dart_id is already 1-free.

2-unlink operation.

This operation corresponds to unlinking two darts that are linked via the β2 function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s).

§Arguments
  • lhs_dart_id: DartIdentifier – ID of the dart to unlink.
§Panics

This method may panic if one of lhs_dart_id is already 2-free.

Source§

impl<T: CoordsFloat + 'static> CMap2<T>

Serializing methods

Source

pub fn to_vtk_binary(&self, writer: impl Write)

Available on crate feature io only.

Generate a legacy VTK file from the map.

§Panics

This function may panic if the internal writing routine fails, i.e.: - Vertex coordinates cannot be cast to f32 or f64 - A vertex cannot be found

Source

pub fn to_vtk_ascii(&self, writer: impl Write)

Available on crate feature io only.

Generate a legacy VTK file from the map.

§Panics

This function may panic if the internal writing routine fails, i.e.: - Vertex coordinates cannot be cast to f32 or f64 - A vertex cannot be found

Source§

impl<T: CoordsFloat> CMap2<T>

Utilities

Source

pub fn set_beta<const I: u8>(&self, dart_id: DartIdType, val: DartIdType)

Available on crate feature utils only.

Set the value of the specified beta function of a dart.

§Arguments
  • dart_id: DartIdentifier – ID of the dart of interest.
  • val: DartIdentifier – Value of the image of dart_id through the beta I function.
§Generic
  • const I: u8 – Beta function to edit.
Source

pub fn set_betas(&self, dart_id: DartIdType, [b0, b1, b2]: [DartIdType; 3])

Available on crate feature utils only.

Set the values of the beta functions of a dart.

§Arguments
  • dart_id: DartIdentifier – ID of the dart of interest.
  • betas: [DartIdentifier; 3] – Value of the images as 0(dart), β1(dart), β2(dart)]
Source

pub fn allocated_size(&self, rootname: &str) -> Result<(), Error>

Available on crate feature utils only.

Computes the total allocated space dedicated to the map.

§Arguments
  • rootname: &str – root of the filename used to save results.
§Return / Panic

The results of this method is saved as a csv file named <rootname>_allocated.csv. The csv file is structured as follows:

key, memory (bytes)
cat1_member1, val
cat1_member2, val
cat1_total, val
cat2_member1, val
cat2_member2, val
cat2_member3, val
cat2_total, val
cat3_member1, val
cat3_total, val

It is mainly designed to be used in dedicated scripts for plotting & analysis.

The metod may panic if, for any reason, it is unable to write to the file.

§Example

An example going over all three size methods is provided in the honeycomb-utils crate. You can run it using the following command:

cargo run --example memory_usage

The output data can be visualized using the memory_usage.py script.

§Errors

The method will return an error if:

  • the file cannot be created,
  • at any point, the program cannot write into the output file.
Source

pub fn effective_size(&self, rootname: &str) -> Result<(), Error>

Available on crate feature utils only.

Computes the total used space dedicated to the map.

§Arguments
  • rootname: &str – root of the filename used to save results.
§Return / Panic

The results of this method is saved as a csv file named <rootname>_allocated.csv. The csv file is structured as follows:

key, memory (bytes)
cat1_member1, val
cat1_member2, val
cat1_total, val
cat2_member1, val
cat2_member2, val
cat2_member3, val
cat2_total, val
cat3_member1, val
cat3_total, val

It is mainly designed to be used in dedicated scripts for plotting & analysis.

The metod may panic if, for any reason, it is unable to write to the file.

§Example

An example going over all three size methods is provided in the honeycomb-utils crate. You can run it using the following command:

cargo run --example memory_usage

The output data can be visualized using the memory_usage.py script.

§Errors

The method will return an error if:

  • the file cannot be created,
  • at any point, the program cannot write into the output file.
Source

pub fn used_size(&self, rootname: &str) -> Result<(), Error>

Available on crate feature utils only.

Computes the actual used space dedicated to the map.

Actual used space refers to the total used space minus empty spots in the structure.

§Arguments
  • rootname: &str – root of the filename used to save results.
§Return / Panic

The results of this method is saved as a csv file named <rootname>_allocated.csv. The csv file is structured as follows:

key, memory (bytes)
cat1_member1, val
cat1_member2, val
cat1_total, val
cat2_member1, val
cat2_member2, val
cat2_member3, val
cat2_total, val
cat3_member1, val
cat3_total, val

It is mainly designed to be used in dedicated scripts for plotting & analysis.

The metod may panic if, for any reason, it is unable to write to the file.

§Example

An example going over all three size methods is provided in the honeycomb-utils crate. You can run it using the following command:

cargo run --example memory_usage

The output data can be visualized using the memory_usage.py script.

§Errors

The method will return an error if:

  • the file cannot be created,
  • at any point, the program cannot write into the output file.

Trait Implementations§

Auto Trait Implementations§

§

impl<T> Freeze for CMap2<T>

§

impl<T> !RefUnwindSafe for CMap2<T>

§

impl<T> Unpin for CMap2<T>
where T: Unpin,

§

impl<T> !UnwindSafe for CMap2<T>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.