pub struct Arc<T, A = Global>{ /* private fields */ }
Expand description
A thread-safe reference-counting pointer. ‘Arc’ stands for ‘Atomically Reference Counted’.
The type Arc<T>
provides shared ownership of a value of type T
,
allocated in the heap. Invoking clone
on Arc
produces
a new Arc
instance, which points to the same allocation on the heap as the
source Arc
, while increasing a reference count. When the last Arc
pointer to a given allocation is destroyed, the value stored in that allocation (often
referred to as “inner value”) is also dropped.
Shared references in Rust disallow mutation by default, and Arc
is no
exception: you cannot generally obtain a mutable reference to something
inside an Arc
. If you do need to mutate through an Arc
, you have several options:
-
Use interior mutability with synchronization primitives like
Mutex
,RwLock
, or one of theAtomic
types. -
Use clone-on-write semantics with
Arc::make_mut
which provides efficient mutation without requiring interior mutability. This approach clones the data only when needed (when there are multiple references) and can be more efficient when mutations are infrequent. -
Use
Arc::get_mut
when you know yourArc
is not shared (has a reference count of 1), which provides direct mutable access to the inner value without any cloning.
use std::sync::Arc;
let mut data = Arc::new(vec![1, 2, 3]);
// This will clone the vector only if there are other references to it
Arc::make_mut(&mut data).push(4);
assert_eq!(*data, vec![1, 2, 3, 4]);
Note: This type is only available on platforms that support atomic
loads and stores of pointers, which includes all platforms that support
the std
crate but not all those which only support alloc
.
This may be detected at compile time using #[cfg(target_has_atomic = "ptr")]
.
§Thread Safety
Unlike Rc<T>
, Arc<T>
uses atomic operations for its reference
counting. This means that it is thread-safe. The disadvantage is that
atomic operations are more expensive than ordinary memory accesses. If you
are not sharing reference-counted allocations between threads, consider using
Rc<T>
for lower overhead. Rc<T>
is a safe default, because the
compiler will catch any attempt to send an Rc<T>
between threads.
However, a library might choose Arc<T>
in order to give library consumers
more flexibility.
Arc<T>
will implement Send
and Sync
as long as the T
implements
Send
and Sync
. Why can’t you put a non-thread-safe type T
in an
Arc<T>
to make it thread-safe? This may be a bit counter-intuitive at
first: after all, isn’t the point of Arc<T>
thread safety? The key is
this: Arc<T>
makes it thread safe to have multiple ownership of the same
data, but it doesn’t add thread safety to its data. Consider
Arc<RefCell<T>>
. RefCell<T>
isn’t Sync
, and if Arc<T>
was always
Send
, Arc<RefCell<T>>
would be as well. But then we’d have a problem:
RefCell<T>
is not thread safe; it keeps track of the borrowing count using
non-atomic operations.
In the end, this means that you may need to pair Arc<T>
with some sort of
std::sync
type, usually Mutex<T>
.
§Breaking cycles with Weak
The downgrade
method can be used to create a non-owning
Weak
pointer. A Weak
pointer can be upgrade
d
to an Arc
, but this will return None
if the value stored in the allocation has
already been dropped. In other words, Weak
pointers do not keep the value
inside the allocation alive; however, they do keep the allocation
(the backing store for the value) alive.
A cycle between Arc
pointers will never be deallocated. For this reason,
Weak
is used to break cycles. For example, a tree could have
strong Arc
pointers from parent nodes to children, and Weak
pointers from children back to their parents.
§Cloning references
Creating a new reference from an existing reference-counted pointer is done using the
Clone
trait implemented for Arc<T>
and Weak<T>
.
use std::sync::Arc;
let foo = Arc::new(vec![1.0, 2.0, 3.0]);
// The two syntaxes below are equivalent.
let a = foo.clone();
let b = Arc::clone(&foo);
// a, b, and foo are all Arcs that point to the same memory location
§Deref
behavior
Arc<T>
automatically dereferences to T
(via the Deref
trait),
so you can call T
’s methods on a value of type Arc<T>
. To avoid name
clashes with T
’s methods, the methods of Arc<T>
itself are associated
functions, called using fully qualified syntax:
use std::sync::Arc;
let my_arc = Arc::new(());
let my_weak = Arc::downgrade(&my_arc);
Arc<T>
’s implementations of traits like Clone
may also be called using
fully qualified syntax. Some people prefer to use fully qualified syntax,
while others prefer using method-call syntax.
use std::sync::Arc;
let arc = Arc::new(());
// Method-call syntax
let arc2 = arc.clone();
// Fully qualified syntax
let arc3 = Arc::clone(&arc);
Weak<T>
does not auto-dereference to T
, because the inner value may have
already been dropped.
§Examples
Sharing some immutable data between threads:
use std::sync::Arc;
use std::thread;
let five = Arc::new(5);
for _ in 0..10 {
let five = Arc::clone(&five);
thread::spawn(move || {
println!("{five:?}");
});
}
Sharing a mutable AtomicUsize
:
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::thread;
let val = Arc::new(AtomicUsize::new(5));
for _ in 0..10 {
let val = Arc::clone(&val);
thread::spawn(move || {
let v = val.fetch_add(1, Ordering::Relaxed);
println!("{v:?}");
});
}
See the rc
documentation for more examples of reference
counting in general.
Implementations§
Source§impl<T> Arc<T>
impl<T> Arc<T>
1.0.0 · Sourcepub fn new(data: T) -> Arc<T>
pub fn new(data: T) -> Arc<T>
Examples found in repository?
28fn main() -> Result<(), Box<dyn Error>> {
29 pel::init();
30 // Set up the dynamics like in the orbit raise.
31 let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
32 let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
33
34 // Define the GEO orbit, and we're just going to maintain it very tightly.
35 let earth_j2000 = almanac.frame_from_uid(EARTH_J2000)?;
36 let orbit = Orbit::try_keplerian(42164.0, 1e-5, 0., 163.0, 75.0, 0.0, epoch, earth_j2000)?;
37 println!("{orbit:x}");
38
39 let sc = Spacecraft::builder()
40 .orbit(orbit)
41 .mass(Mass::from_dry_and_prop_masses(1000.0, 1000.0)) // 1000 kg of dry mass and prop, totalling 2.0 tons
42 .srp(SRPData::from_area(3.0 * 6.0)) // Assuming 1 kW/m^2 or 18 kW, giving a margin of 4.35 kW for on-propulsion consumption
43 .thruster(Thruster {
44 // "NEXT-STEP" row in Table 2
45 isp_s: 4435.0,
46 thrust_N: 0.472,
47 })
48 .mode(GuidanceMode::Thrust) // Start thrusting immediately.
49 .build();
50
51 // Set up the spacecraft dynamics like in the orbit raise example.
52
53 let prop_time = 30.0 * Unit::Day;
54
55 // Define the guidance law -- we're just using a Ruggiero controller as demonstrated in AAS-2004-5089.
56 let objectives = &[
57 Objective::within_tolerance(StateParameter::SMA, 42_164.0, 5.0), // 5 km
58 Objective::within_tolerance(StateParameter::Eccentricity, 0.001, 5e-5),
59 Objective::within_tolerance(StateParameter::Inclination, 0.05, 1e-2),
60 ];
61
62 let ruggiero_ctrl = Ruggiero::from_max_eclipse(objectives, sc, 0.2)?;
63 println!("{ruggiero_ctrl}");
64
65 let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
66
67 let mut jgm3_meta = MetaFile {
68 uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
69 crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
70 };
71 jgm3_meta.process(true)?;
72
73 let harmonics = Harmonics::from_stor(
74 almanac.frame_from_uid(IAU_EARTH_FRAME)?,
75 HarmonicsMem::from_cof(&jgm3_meta.uri, 8, 8, true)?,
76 );
77 orbital_dyn.accel_models.push(harmonics);
78
79 let srp_dyn = SolarPressure::default(EARTH_J2000, almanac.clone())?;
80 let sc_dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn)
81 .with_guidance_law(ruggiero_ctrl.clone());
82
83 println!("{sc_dynamics}");
84
85 // Finally, let's use the Monte Carlo framework built into Nyx to propagate spacecraft.
86
87 // Let's start by defining the dispersion.
88 // The MultivariateNormal structure allows us to define the dispersions in any of the orbital parameters, but these are applied directly in the Cartesian state space.
89 // Note that additional validation on the MVN is in progress -- https://github.com/nyx-space/nyx/issues/339.
90 let mc_rv = MvnSpacecraft::new(
91 sc,
92 vec![StateDispersion::zero_mean(StateParameter::SMA, 3.0)],
93 )?;
94
95 let my_mc = MonteCarlo::new(
96 sc, // Nominal state
97 mc_rv,
98 "03_geo_sk".to_string(), // Scenario name
99 None, // No specific seed specified, so one will be drawn from the computer's entropy.
100 );
101
102 // Build the propagator setup.
103 let setup = Propagator::rk89(
104 sc_dynamics.clone(),
105 IntegratorOptions::builder()
106 .min_step(10.0_f64.seconds())
107 .error_ctrl(ErrorControl::RSSCartesianStep)
108 .build(),
109 );
110
111 let num_runs = 25;
112 let rslts = my_mc.run_until_epoch(setup, almanac.clone(), sc.epoch() + prop_time, num_runs);
113
114 assert_eq!(rslts.runs.len(), num_runs);
115
116 // For all of the resulting trajectories, we'll want to compute the percentage of penumbra and umbra.
117
118 rslts.to_parquet(
119 "03_geo_sk.parquet",
120 Some(vec![
121 &EclipseLocator::cislunar(almanac.clone()).to_penumbra_event()
122 ]),
123 ExportCfg::default(),
124 almanac,
125 )?;
126
127 Ok(())
128}
More examples
27fn main() -> Result<(), Box<dyn Error>> {
28 pel::init();
29
30 // Dynamics models require planetary constants and ephemerides to be defined.
31 // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
32 // This will automatically download the DE440s planetary ephemeris,
33 // the daily-updated Earth Orientation Parameters, the high fidelity Moon orientation
34 // parameters (for the Moon Mean Earth and Moon Principal Axes frames), and the PCK11
35 // planetary constants kernels.
36 // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
37 // Note that we place the Almanac into an Arc so we can clone it cheaply and provide read-only
38 // references to many functions.
39 let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
40 // Fetch the EME2000 frame from the Almabac
41 let eme2k = almanac.frame_from_uid(EARTH_J2000).unwrap();
42 // Define the orbit epoch
43 let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
44
45 // Build the spacecraft itself.
46 // Using slide 6 of https://aerospace.org/sites/default/files/2018-11/Davis-Mayberry_HPSEP_11212018.pdf
47 // for the "next gen" SEP characteristics.
48
49 // GTO start
50 let orbit = Orbit::keplerian(24505.9, 0.725, 7.05, 0.0, 0.0, 0.0, epoch, eme2k);
51
52 let sc = Spacecraft::builder()
53 .orbit(orbit)
54 .mass(Mass::from_dry_and_prop_masses(1000.0, 1000.0)) // 1000 kg of dry mass and prop, totalling 2.0 tons
55 .srp(SRPData::from_area(3.0 * 6.0)) // Assuming 1 kW/m^2 or 18 kW, giving a margin of 4.35 kW for on-propulsion consumption
56 .thruster(Thruster {
57 // "NEXT-STEP" row in Table 2
58 isp_s: 4435.0,
59 thrust_N: 0.472,
60 })
61 .mode(GuidanceMode::Thrust) // Start thrusting immediately.
62 .build();
63
64 let prop_time = 180.0 * Unit::Day;
65
66 // Define the guidance law -- we're just using a Ruggiero controller as demonstrated in AAS-2004-5089.
67 let objectives = &[
68 Objective::within_tolerance(StateParameter::SMA, 42_165.0, 20.0),
69 Objective::within_tolerance(StateParameter::Eccentricity, 0.001, 5e-5),
70 Objective::within_tolerance(StateParameter::Inclination, 0.05, 1e-2),
71 ];
72
73 // Ensure that we only thrust if we have more than 20% illumination.
74 let ruggiero_ctrl = Ruggiero::from_max_eclipse(objectives, sc, 0.2).unwrap();
75 println!("{ruggiero_ctrl}");
76
77 // Define the high fidelity dynamics
78
79 // Set up the spacecraft dynamics.
80
81 // Specify that the orbital dynamics must account for the graviational pull of the Moon and the Sun.
82 // The gravity of the Earth will also be accounted for since the spaceraft in an Earth orbit.
83 let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
84
85 // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
86 // We're using the JGM3 model here, which is the default in GMAT.
87 let mut jgm3_meta = MetaFile {
88 uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
89 crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
90 };
91 // And let's download it if we don't have it yet.
92 jgm3_meta.process(true)?;
93
94 // Build the spherical harmonics.
95 // The harmonics must be computed in the body fixed frame.
96 // We're using the long term prediction of the Earth centered Earth fixed frame, IAU Earth.
97 let harmonics = Harmonics::from_stor(
98 almanac.frame_from_uid(IAU_EARTH_FRAME)?,
99 HarmonicsMem::from_cof(&jgm3_meta.uri, 8, 8, true).unwrap(),
100 );
101
102 // Include the spherical harmonics into the orbital dynamics.
103 orbital_dyn.accel_models.push(harmonics);
104
105 // We define the solar radiation pressure, using the default solar flux and accounting only
106 // for the eclipsing caused by the Earth.
107 let srp_dyn = SolarPressure::default(EARTH_J2000, almanac.clone())?;
108
109 // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
110 // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
111 let sc_dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn)
112 .with_guidance_law(ruggiero_ctrl.clone());
113
114 println!("{orbit:x}");
115
116 // We specify a minimum step in the propagator because the Ruggiero control would otherwise drive this step very low.
117 let (final_state, traj) = Propagator::rk89(
118 sc_dynamics.clone(),
119 IntegratorOptions::builder()
120 .min_step(10.0_f64.seconds())
121 .error_ctrl(ErrorControl::RSSCartesianStep)
122 .build(),
123 )
124 .with(sc, almanac.clone())
125 .for_duration_with_traj(prop_time)?;
126
127 let prop_usage = sc.mass.prop_mass_kg - final_state.mass.prop_mass_kg;
128 println!("{:x}", final_state.orbit);
129 println!("prop usage: {prop_usage:.3} kg");
130
131 // Finally, export the results for analysis, including the penumbra percentage throughout the orbit raise.
132 traj.to_parquet(
133 "./03_geo_raise.parquet",
134 Some(vec![
135 &EclipseLocator::cislunar(almanac.clone()).to_penumbra_event()
136 ]),
137 ExportCfg::default(),
138 almanac,
139 )?;
140
141 for status_line in ruggiero_ctrl.status(&final_state) {
142 println!("{status_line}");
143 }
144
145 ruggiero_ctrl
146 .achieved(&final_state)
147 .expect("objective not achieved");
148
149 Ok(())
150}
26fn main() -> Result<(), Box<dyn Error>> {
27 pel::init();
28 // Dynamics models require planetary constants and ephemerides to be defined.
29 // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
30 // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
31
32 // Download the regularly update of the James Webb Space Telescope reconstucted (or definitive) ephemeris.
33 // Refer to https://naif.jpl.nasa.gov/pub/naif/JWST/kernels/spk/aareadme.txt for details.
34 let mut latest_jwst_ephem = MetaFile {
35 uri: "https://naif.jpl.nasa.gov/pub/naif/JWST/kernels/spk/jwst_rec.bsp".to_string(),
36 crc32: None,
37 };
38 latest_jwst_ephem.process(true)?;
39
40 // Load this ephem in the general Almanac we're using for this analysis.
41 let almanac = Arc::new(
42 MetaAlmanac::latest()
43 .map_err(Box::new)?
44 .load_from_metafile(latest_jwst_ephem, true)?,
45 );
46
47 // By loading this ephemeris file in the ANISE GUI or ANISE CLI, we can find the NAIF ID of the JWST
48 // in the BSP. We need this ID in order to query the ephemeris.
49 const JWST_NAIF_ID: i32 = -170;
50 // Let's build a frame in the J2000 orientation centered on the JWST.
51 const JWST_J2000: Frame = Frame::from_ephem_j2000(JWST_NAIF_ID);
52
53 // Since the ephemeris file is updated regularly, we'll just grab the latest state in the ephem.
54 let (earliest_epoch, latest_epoch) = almanac.spk_domain(JWST_NAIF_ID)?;
55 println!("JWST defined from {earliest_epoch} to {latest_epoch}");
56 // Fetch the state, printing it in the Earth J2000 frame.
57 let jwst_orbit = almanac.transform(JWST_J2000, EARTH_J2000, latest_epoch, None)?;
58 println!("{jwst_orbit:x}");
59
60 // Build the spacecraft
61 // SRP area assumed to be the full sunshield and mass if 6200.0 kg, c.f. https://webb.nasa.gov/content/about/faqs/facts.html
62 // SRP Coefficient of reflectivity assumed to be that of Kapton, i.e. 2 - 0.44 = 1.56, table 1 from https://amostech.com/TechnicalPapers/2018/Poster/Bengtson.pdf
63 let jwst = Spacecraft::builder()
64 .orbit(jwst_orbit)
65 .srp(SRPData {
66 area_m2: 21.197 * 14.162,
67 coeff_reflectivity: 1.56,
68 })
69 .mass(Mass::from_dry_mass(6200.0))
70 .build();
71
72 // Build up the spacecraft uncertainty builder.
73 // We can use the spacecraft uncertainty structure to build this up.
74 // We start by specifying the nominal state (as defined above), then the uncertainty in position and velocity
75 // in the RIC frame. We could also specify the Cr, Cd, and mass uncertainties, but these aren't accounted for until
76 // Nyx can also estimate the deviation of the spacecraft parameters.
77 let jwst_uncertainty = SpacecraftUncertainty::builder()
78 .nominal(jwst)
79 .frame(LocalFrame::RIC)
80 .x_km(0.5)
81 .y_km(0.3)
82 .z_km(1.5)
83 .vx_km_s(1e-4)
84 .vy_km_s(0.6e-3)
85 .vz_km_s(3e-3)
86 .build();
87
88 println!("{jwst_uncertainty}");
89
90 // Build the Kalman filter estimate.
91 // Note that we could have used the KfEstimate structure directly (as seen throughout the OD integration tests)
92 // but this approach requires quite a bit more boilerplate code.
93 let jwst_estimate = jwst_uncertainty.to_estimate()?;
94
95 // Set up the spacecraft dynamics.
96 // We'll use the point masses of the Earth, Sun, Jupiter (barycenter, because it's in the DE440), and the Moon.
97 // We'll also enable solar radiation pressure since the James Webb has a huge and highly reflective sun shield.
98
99 let orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN, JUPITER_BARYCENTER]);
100 let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
101
102 // Finalize setting up the dynamics.
103 let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
104
105 // Build the propagator set up to use for the whole analysis.
106 let setup = Propagator::default(dynamics);
107
108 // All of the analysis will use this duration.
109 let prediction_duration = 6.5 * Unit::Day;
110
111 // === Covariance mapping ===
112 // For the covariance mapping / prediction, we'll use the common orbit determination approach.
113 // This is done by setting up a spacecraft Kalman filter OD process, and predicting for the analysis duration.
114
115 // Build the propagation instance for the OD process.
116 let odp = SpacecraftKalmanOD::new(
117 setup.clone(),
118 KalmanVariant::DeviationTracking,
119 None,
120 BTreeMap::new(),
121 almanac.clone(),
122 );
123
124 // The prediction step is 1 minute by default, configured in the OD process, i.e. how often we want to know the covariance.
125 assert_eq!(odp.max_step, 1_i64.minutes());
126 // Finally, predict, and export the trajectory with covariance to a parquet file.
127 let od_sol = odp.predict_for(jwst_estimate, prediction_duration)?;
128 od_sol.to_parquet("./02_jwst_covar_map.parquet", ExportCfg::default())?;
129
130 // === Monte Carlo framework ===
131 // Nyx comes with a complete multi-threaded Monte Carlo frame. It's blazing fast.
132
133 let my_mc = MonteCarlo::new(
134 jwst, // Nominal state
135 jwst_estimate.to_random_variable()?,
136 "02_jwst".to_string(), // Scenario name
137 None, // No specific seed specified, so one will be drawn from the computer's entropy.
138 );
139
140 let num_runs = 5_000;
141 let rslts = my_mc.run_until_epoch(
142 setup,
143 almanac.clone(),
144 jwst.epoch() + prediction_duration,
145 num_runs,
146 );
147
148 assert_eq!(rslts.runs.len(), num_runs);
149 // Finally, export these results, computing the eclipse percentage for all of these results.
150
151 // For all of the resulting trajectories, we'll want to compute the percentage of penumbra and umbra.
152 let eclipse_loc = EclipseLocator::cislunar(almanac.clone());
153 let umbra_event = eclipse_loc.to_umbra_event();
154 let penumbra_event = eclipse_loc.to_penumbra_event();
155
156 rslts.to_parquet(
157 "02_jwst_monte_carlo.parquet",
158 Some(vec![&umbra_event, &penumbra_event]),
159 ExportCfg::default(),
160 almanac,
161 )?;
162
163 Ok(())
164}
26fn main() -> Result<(), Box<dyn Error>> {
27 pel::init();
28 // Dynamics models require planetary constants and ephemerides to be defined.
29 // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
30 // This will automatically download the DE440s planetary ephemeris,
31 // the daily-updated Earth Orientation Parameters, the high fidelity Moon orientation
32 // parameters (for the Moon Mean Earth and Moon Principal Axes frames), and the PCK11
33 // planetary constants kernels.
34 // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
35 // Note that we place the Almanac into an Arc so we can clone it cheaply and provide read-only
36 // references to many functions.
37 let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
38 // Define the orbit epoch
39 let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
40
41 // Define the orbit.
42 // First we need to fetch the Earth J2000 from information from the Almanac.
43 // This allows the frame to include the gravitational parameters and the shape of the Earth,
44 // defined as a tri-axial ellipoid. Note that this shape can be changed manually or in the Almanac
45 // by loading a different set of planetary constants.
46 let earth_j2000 = almanac.frame_from_uid(EARTH_J2000)?;
47
48 // Placing this GEO bird just above Colorado.
49 // In theory, the eccentricity is zero, but in practice, it's about 1e-5 to 1e-6 at best.
50 let orbit = Orbit::try_keplerian(42164.0, 1e-5, 0., 163.0, 75.0, 0.0, epoch, earth_j2000)?;
51 // Print in in Keplerian form.
52 println!("{orbit:x}");
53
54 let state_bf = almanac.transform_to(orbit, IAU_EARTH_FRAME, None)?;
55 let (orig_lat_deg, orig_long_deg, orig_alt_km) = state_bf.latlongalt()?;
56
57 // Nyx is used for high fidelity propagation, not Keplerian propagation as above.
58 // Nyx only propagates Spacecraft at the moment, which allows it to account for acceleration
59 // models such as solar radiation pressure.
60
61 // Let's build a cubesat sized spacecraft, with an SRP area of 10 cm^2 and a mass of 9.6 kg.
62 let sc = Spacecraft::builder()
63 .orbit(orbit)
64 .mass(Mass::from_dry_mass(9.60))
65 .srp(SRPData {
66 area_m2: 10e-4,
67 coeff_reflectivity: 1.1,
68 })
69 .build();
70 println!("{sc:x}");
71
72 // Set up the spacecraft dynamics.
73
74 // Specify that the orbital dynamics must account for the graviational pull of the Moon and the Sun.
75 // The gravity of the Earth will also be accounted for since the spaceraft in an Earth orbit.
76 let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
77
78 // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
79 // We're using the JGM3 model here, which is the default in GMAT.
80 let mut jgm3_meta = MetaFile {
81 uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
82 crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
83 };
84 // And let's download it if we don't have it yet.
85 jgm3_meta.process(true)?;
86
87 // Build the spherical harmonics.
88 // The harmonics must be computed in the body fixed frame.
89 // We're using the long term prediction of the Earth centered Earth fixed frame, IAU Earth.
90 let harmonics_21x21 = Harmonics::from_stor(
91 almanac.frame_from_uid(IAU_EARTH_FRAME)?,
92 HarmonicsMem::from_cof(&jgm3_meta.uri, 21, 21, true).unwrap(),
93 );
94
95 // Include the spherical harmonics into the orbital dynamics.
96 orbital_dyn.accel_models.push(harmonics_21x21);
97
98 // We define the solar radiation pressure, using the default solar flux and accounting only
99 // for the eclipsing caused by the Earth and Moon.
100 let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
101
102 // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
103 // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
104 let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
105
106 println!("{dynamics}");
107
108 // Finally, let's propagate this orbit to the same epoch as above.
109 // The first returned value is the spacecraft state at the final epoch.
110 // The second value is the full trajectory where the step size is variable step used by the propagator.
111 let (future_sc, trajectory) = Propagator::default(dynamics)
112 .with(sc, almanac.clone())
113 .until_epoch_with_traj(epoch + Unit::Century * 0.03)?;
114
115 println!("=== High fidelity propagation ===");
116 println!(
117 "SMA changed by {:.3} km",
118 orbit.sma_km()? - future_sc.orbit.sma_km()?
119 );
120 println!(
121 "ECC changed by {:.6}",
122 orbit.ecc()? - future_sc.orbit.ecc()?
123 );
124 println!(
125 "INC changed by {:.3e} deg",
126 orbit.inc_deg()? - future_sc.orbit.inc_deg()?
127 );
128 println!(
129 "RAAN changed by {:.3} deg",
130 orbit.raan_deg()? - future_sc.orbit.raan_deg()?
131 );
132 println!(
133 "AOP changed by {:.3} deg",
134 orbit.aop_deg()? - future_sc.orbit.aop_deg()?
135 );
136 println!(
137 "TA changed by {:.3} deg",
138 orbit.ta_deg()? - future_sc.orbit.ta_deg()?
139 );
140
141 // We also have access to the full trajectory throughout the propagation.
142 println!("{trajectory}");
143
144 println!("Spacecraft params after 3 years without active control:\n{future_sc:x}");
145
146 // With the trajectory, let's build a few data products.
147
148 // 1. Export the trajectory as a parquet file, which includes the Keplerian orbital elements.
149
150 let analysis_step = Unit::Minute * 5;
151
152 trajectory.to_parquet(
153 "./03_geo_hf_prop.parquet",
154 Some(vec![
155 &EclipseLocator::cislunar(almanac.clone()).to_penumbra_event()
156 ]),
157 ExportCfg::builder().step(analysis_step).build(),
158 almanac.clone(),
159 )?;
160
161 // 2. Compute the latitude, longitude, and altitude throughout the trajectory by rotating the spacecraft position into the Earth body fixed frame.
162
163 // We iterate over the trajectory, grabbing a state every two minutes.
164 let mut offset_s = vec![];
165 let mut epoch_str = vec![];
166 let mut longitude_deg = vec![];
167 let mut latitude_deg = vec![];
168 let mut altitude_km = vec![];
169
170 for state in trajectory.every(analysis_step) {
171 // Convert the GEO bird state into the body fixed frame, and keep track of its latitude, longitude, and altitude.
172 // These define the GEO stationkeeping box.
173
174 let this_epoch = state.epoch();
175
176 offset_s.push((this_epoch - orbit.epoch).to_seconds());
177 epoch_str.push(this_epoch.to_isoformat());
178
179 let state_bf = almanac.transform_to(state.orbit, IAU_EARTH_FRAME, None)?;
180 let (lat_deg, long_deg, alt_km) = state_bf.latlongalt()?;
181 longitude_deg.push(long_deg);
182 latitude_deg.push(lat_deg);
183 altitude_km.push(alt_km);
184 }
185
186 println!(
187 "Longitude changed by {:.3} deg -- Box is 0.1 deg E-W",
188 orig_long_deg - longitude_deg.last().unwrap()
189 );
190
191 println!(
192 "Latitude changed by {:.3} deg -- Box is 0.05 deg N-S",
193 orig_lat_deg - latitude_deg.last().unwrap()
194 );
195
196 println!(
197 "Altitude changed by {:.3} km -- Box is 30 km",
198 orig_alt_km - altitude_km.last().unwrap()
199 );
200
201 // Build the station keeping data frame.
202 let mut sk_df = df!(
203 "Offset (s)" => offset_s.clone(),
204 "Epoch (UTC)" => epoch_str.clone(),
205 "Longitude E-W (deg)" => longitude_deg,
206 "Latitude N-S (deg)" => latitude_deg,
207 "Altitude (km)" => altitude_km,
208
209 )?;
210
211 // Create a file to write the Parquet to
212 let file = File::create("./03_geo_lla.parquet").expect("Could not create file");
213
214 // Create a ParquetWriter and write the DataFrame to the file
215 ParquetWriter::new(file).finish(&mut sk_df)?;
216
217 Ok(())
218}
33fn main() -> Result<(), Box<dyn Error>> {
34 pel::init();
35
36 // ====================== //
37 // === ALMANAC SET UP === //
38 // ====================== //
39
40 // Dynamics models require planetary constants and ephemerides to be defined.
41 // Let's start by grabbing those by using ANISE's MetaAlmanac.
42
43 let data_folder: PathBuf = [env!("CARGO_MANIFEST_DIR"), "examples", "04_lro_od"]
44 .iter()
45 .collect();
46
47 let meta = data_folder.join("lro-dynamics.dhall");
48
49 // Load this ephem in the general Almanac we're using for this analysis.
50 let mut almanac = MetaAlmanac::new(meta.to_string_lossy().to_string())
51 .map_err(Box::new)?
52 .process(true)
53 .map_err(Box::new)?;
54
55 let mut moon_pc = almanac.planetary_data.get_by_id(MOON)?;
56 moon_pc.mu_km3_s2 = 4902.74987;
57 almanac.planetary_data.set_by_id(MOON, moon_pc)?;
58
59 let mut earth_pc = almanac.planetary_data.get_by_id(EARTH)?;
60 earth_pc.mu_km3_s2 = 398600.436;
61 almanac.planetary_data.set_by_id(EARTH, earth_pc)?;
62
63 // Save this new kernel for reuse.
64 // In an operational context, this would be part of the "Lock" process, and should not change throughout the mission.
65 almanac
66 .planetary_data
67 .save_as(&data_folder.join("lro-specific.pca"), true)?;
68
69 // Lock the almanac (an Arc is a read only structure).
70 let almanac = Arc::new(almanac);
71
72 // Orbit determination requires a Trajectory structure, which can be saved as parquet file.
73 // In our case, the trajectory comes from the BSP file, so we need to build a Trajectory from the almanac directly.
74 // To query the Almanac, we need to build the LRO frame in the J2000 orientation in our case.
75 // Inspecting the LRO BSP in the ANISE GUI shows us that NASA has assigned ID -85 to LRO.
76 let lro_frame = Frame::from_ephem_j2000(-85);
77
78 // To build the trajectory we need to provide a spacecraft template.
79 let sc_template = Spacecraft::builder()
80 .mass(Mass::from_dry_and_prop_masses(1018.0, 900.0)) // Launch masses
81 .srp(SRPData {
82 // SRP configuration is arbitrary, but we will be estimating it anyway.
83 area_m2: 3.9 * 2.7,
84 coeff_reflectivity: 0.96,
85 })
86 .orbit(Orbit::zero(MOON_J2000)) // Setting a zero orbit here because it's just a template
87 .build();
88 // Now we can build the trajectory from the BSP file.
89 // We'll arbitrarily set the tracking arc to 24 hours with a five second time step.
90 let traj_as_flown = Traj::from_bsp(
91 lro_frame,
92 MOON_J2000,
93 almanac.clone(),
94 sc_template,
95 5.seconds(),
96 Some(Epoch::from_str("2024-01-01 00:00:00 UTC")?),
97 Some(Epoch::from_str("2024-01-02 00:00:00 UTC")?),
98 Aberration::LT,
99 Some("LRO".to_string()),
100 )?;
101
102 println!("{traj_as_flown}");
103
104 // ====================== //
105 // === MODEL MATCHING === //
106 // ====================== //
107
108 // Set up the spacecraft dynamics.
109
110 // Specify that the orbital dynamics must account for the graviational pull of the Earth and the Sun.
111 // The gravity of the Moon will also be accounted for since the spaceraft in a lunar orbit.
112 let mut orbital_dyn = OrbitalDynamics::point_masses(vec![EARTH, SUN, JUPITER_BARYCENTER]);
113
114 // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
115 // We're using the GRAIL JGGRX model.
116 let mut jggrx_meta = MetaFile {
117 uri: "http://public-data.nyxspace.com/nyx/models/Luna_jggrx_1500e_sha.tab.gz".to_string(),
118 crc32: Some(0x6bcacda8), // Specifying the CRC32 avoids redownloading it if it's cached.
119 };
120 // And let's download it if we don't have it yet.
121 jggrx_meta.process(true)?;
122
123 // Build the spherical harmonics.
124 // The harmonics must be computed in the body fixed frame.
125 // We're using the long term prediction of the Moon principal axes frame.
126 let moon_pa_frame = MOON_PA_FRAME.with_orient(31008);
127 let sph_harmonics = Harmonics::from_stor(
128 almanac.frame_from_uid(moon_pa_frame)?,
129 HarmonicsMem::from_shadr(&jggrx_meta.uri, 80, 80, true)?,
130 );
131
132 // Include the spherical harmonics into the orbital dynamics.
133 orbital_dyn.accel_models.push(sph_harmonics);
134
135 // We define the solar radiation pressure, using the default solar flux and accounting only
136 // for the eclipsing caused by the Earth and Moon.
137 // Note that by default, enabling the SolarPressure model will also enable the estimation of the coefficient of reflectivity.
138 let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
139
140 // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
141 // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
142 let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
143
144 println!("{dynamics}");
145
146 // Now we can build the propagator.
147 let setup = Propagator::default_dp78(dynamics.clone());
148
149 // For reference, let's build the trajectory with Nyx's models from that LRO state.
150 let (sim_final, traj_as_sim) = setup
151 .with(*traj_as_flown.first(), almanac.clone())
152 .until_epoch_with_traj(traj_as_flown.last().epoch())?;
153
154 println!("SIM INIT: {:x}", traj_as_flown.first());
155 println!("SIM FINAL: {sim_final:x}");
156 // Compute RIC difference between SIM and LRO ephem
157 let sim_lro_delta = sim_final
158 .orbit
159 .ric_difference(&traj_as_flown.last().orbit)?;
160 println!("{traj_as_sim}");
161 println!(
162 "SIM v LRO - RIC Position (m): {:.3}",
163 sim_lro_delta.radius_km * 1e3
164 );
165 println!(
166 "SIM v LRO - RIC Velocity (m/s): {:.3}",
167 sim_lro_delta.velocity_km_s * 1e3
168 );
169
170 traj_as_sim.ric_diff_to_parquet(
171 &traj_as_flown,
172 "./04_lro_sim_truth_error.parquet",
173 ExportCfg::default(),
174 )?;
175
176 // ==================== //
177 // === OD SIMULATOR === //
178 // ==================== //
179
180 // After quite some time trying to exactly match the model, we still end up with an oscillatory difference on the order of 150 meters between the propagated state
181 // and the truth LRO state.
182
183 // Therefore, we will actually run an estimation from a dispersed LRO state.
184 // The sc_seed is the true LRO state from the BSP.
185 let sc_seed = *traj_as_flown.first();
186
187 // Load the Deep Space Network ground stations.
188 // Nyx allows you to build these at runtime but it's pretty static so we can just load them from YAML.
189 let ground_station_file: PathBuf = [
190 env!("CARGO_MANIFEST_DIR"),
191 "examples",
192 "04_lro_od",
193 "dsn-network.yaml",
194 ]
195 .iter()
196 .collect();
197
198 let devices = GroundStation::load_named(ground_station_file)?;
199
200 // Typical OD software requires that you specify your own tracking schedule or you'll have overlapping measurements.
201 // Nyx can build a tracking schedule for you based on the first station with access.
202 let trkconfg_yaml: PathBuf = [
203 env!("CARGO_MANIFEST_DIR"),
204 "examples",
205 "04_lro_od",
206 "tracking-cfg.yaml",
207 ]
208 .iter()
209 .collect();
210
211 let configs: BTreeMap<String, TrkConfig> = TrkConfig::load_named(trkconfg_yaml)?;
212
213 // Build the tracking arc simulation to generate a "standard measurement".
214 let mut trk = TrackingArcSim::<Spacecraft, GroundStation>::new(
215 devices.clone(),
216 traj_as_flown.clone(),
217 configs,
218 )?;
219
220 trk.build_schedule(almanac.clone())?;
221 let arc = trk.generate_measurements(almanac.clone())?;
222 // Save the simulated tracking data
223 arc.to_parquet_simple("./04_lro_simulated_tracking.parquet")?;
224
225 // We'll note that in our case, we have continuous coverage of LRO when the vehicle is not behind the Moon.
226 println!("{arc}");
227
228 // Now that we have simulated measurements, we'll run the orbit determination.
229
230 // ===================== //
231 // === OD ESTIMATION === //
232 // ===================== //
233
234 let sc = SpacecraftUncertainty::builder()
235 .nominal(sc_seed)
236 .frame(LocalFrame::RIC)
237 .x_km(0.5)
238 .y_km(0.5)
239 .z_km(0.5)
240 .vx_km_s(5e-3)
241 .vy_km_s(5e-3)
242 .vz_km_s(5e-3)
243 .build();
244
245 // Build the filter initial estimate, which we will reuse in the filter.
246 let initial_estimate = sc.to_estimate()?;
247
248 println!("== FILTER STATE ==\n{sc_seed:x}\n{initial_estimate}");
249
250 // Build the SNC in the Moon J2000 frame, specified as a velocity noise over time.
251 let process_noise = ProcessNoise3D::from_velocity_km_s(
252 &[1.8e-9, 1.8e-9, 1.8e-9],
253 1 * Unit::Hour,
254 10 * Unit::Minute,
255 None,
256 );
257
258 println!("{process_noise}");
259
260 // We'll set up the OD process to reject measurements whose residuals are move than 3 sigmas away from what we expect.
261 let odp = SpacecraftKalmanOD::new(
262 setup,
263 KalmanVariant::ReferenceUpdate,
264 Some(ResidRejectCrit::default()),
265 devices,
266 almanac.clone(),
267 )
268 .with_process_noise(process_noise);
269
270 let od_sol = odp.process_arc(initial_estimate, &arc)?;
271
272 let ric_err = traj_as_flown
273 .at(od_sol.estimates.last().unwrap().epoch())?
274 .orbit
275 .ric_difference(&od_sol.estimates.last().unwrap().orbital_state())?;
276 println!("== RIC at end ==");
277 println!("RIC Position (m): {}", ric_err.radius_km * 1e3);
278 println!("RIC Velocity (m/s): {}", ric_err.velocity_km_s * 1e3);
279
280 println!(
281 "Num residuals rejected: #{}",
282 od_sol.rejected_residuals().len()
283 );
284 println!(
285 "Percentage within +/-3: {}",
286 od_sol.residual_ratio_within_threshold(3.0).unwrap()
287 );
288 println!("Ratios normal? {}", od_sol.is_normal(None).unwrap());
289
290 od_sol.to_parquet("./04_lro_od_results.parquet", ExportCfg::default())?;
291
292 // In our case, we have the truth trajectory from NASA.
293 // So we can compute the RIC state difference between the real LRO ephem and what we've just estimated.
294 // Export the OD trajectory first.
295 let od_trajectory = od_sol.to_traj()?;
296 // Build the RIC difference.
297 od_trajectory.ric_diff_to_parquet(
298 &traj_as_flown,
299 "./04_lro_od_truth_error.parquet",
300 ExportCfg::default(),
301 )?;
302
303 Ok(())
304}
30fn main() -> Result<(), Box<dyn Error>> {
31 pel::init();
32 // Dynamics models require planetary constants and ephemerides to be defined.
33 // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
34 // This will automatically download the DE440s planetary ephemeris,
35 // the daily-updated Earth Orientation Parameters, the high fidelity Moon orientation
36 // parameters (for the Moon Mean Earth and Moon Principal Axes frames), and the PCK11
37 // planetary constants kernels.
38 // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
39 // Note that we place the Almanac into an Arc so we can clone it cheaply and provide read-only
40 // references to many functions.
41 let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
42 // Define the orbit epoch
43 let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
44
45 // Define the orbit.
46 // First we need to fetch the Earth J2000 from information from the Almanac.
47 // This allows the frame to include the gravitational parameters and the shape of the Earth,
48 // defined as a tri-axial ellipoid. Note that this shape can be changed manually or in the Almanac
49 // by loading a different set of planetary constants.
50 let earth_j2000 = almanac.frame_from_uid(EARTH_J2000)?;
51
52 let orbit =
53 Orbit::try_keplerian_altitude(300.0, 0.015, 68.5, 65.2, 75.0, 0.0, epoch, earth_j2000)?;
54 // Print in in Keplerian form.
55 println!("{orbit:x}");
56
57 // There are two ways to propagate an orbit. We can make a quick approximation assuming only two-body
58 // motion. This is a useful first order approximation but it isn't used in real-world applications.
59
60 // This approach is a feature of ANISE.
61 let future_orbit_tb = orbit.at_epoch(epoch + Unit::Day * 3)?;
62 println!("{future_orbit_tb:x}");
63
64 // Two body propagation relies solely on Kepler's laws, so only the true anomaly will change.
65 println!(
66 "SMA changed by {:.3e} km",
67 orbit.sma_km()? - future_orbit_tb.sma_km()?
68 );
69 println!(
70 "ECC changed by {:.3e}",
71 orbit.ecc()? - future_orbit_tb.ecc()?
72 );
73 println!(
74 "INC changed by {:.3e} deg",
75 orbit.inc_deg()? - future_orbit_tb.inc_deg()?
76 );
77 println!(
78 "RAAN changed by {:.3e} deg",
79 orbit.raan_deg()? - future_orbit_tb.raan_deg()?
80 );
81 println!(
82 "AOP changed by {:.3e} deg",
83 orbit.aop_deg()? - future_orbit_tb.aop_deg()?
84 );
85 println!(
86 "TA changed by {:.3} deg",
87 orbit.ta_deg()? - future_orbit_tb.ta_deg()?
88 );
89
90 // Nyx is used for high fidelity propagation, not Keplerian propagation as above.
91 // Nyx only propagates Spacecraft at the moment, which allows it to account for acceleration
92 // models such as solar radiation pressure.
93
94 // Let's build a cubesat sized spacecraft, with an SRP area of 10 cm^2 and a mass of 9.6 kg.
95 let sc = Spacecraft::builder()
96 .orbit(orbit)
97 .mass(Mass::from_dry_mass(9.60))
98 .srp(SRPData {
99 area_m2: 10e-4,
100 coeff_reflectivity: 1.1,
101 })
102 .build();
103 println!("{sc:x}");
104
105 // Set up the spacecraft dynamics.
106
107 // Specify that the orbital dynamics must account for the graviational pull of the Moon and the Sun.
108 // The gravity of the Earth will also be accounted for since the spaceraft in an Earth orbit.
109 let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
110
111 // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
112 // We're using the JGM3 model here, which is the default in GMAT.
113 let mut jgm3_meta = MetaFile {
114 uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
115 crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
116 };
117 // And let's download it if we don't have it yet.
118 jgm3_meta.process(true)?;
119
120 // Build the spherical harmonics.
121 // The harmonics must be computed in the body fixed frame.
122 // We're using the long term prediction of the Earth centered Earth fixed frame, IAU Earth.
123 let harmonics_21x21 = Harmonics::from_stor(
124 almanac.frame_from_uid(IAU_EARTH_FRAME)?,
125 HarmonicsMem::from_cof(&jgm3_meta.uri, 21, 21, true).unwrap(),
126 );
127
128 // Include the spherical harmonics into the orbital dynamics.
129 orbital_dyn.accel_models.push(harmonics_21x21);
130
131 // We define the solar radiation pressure, using the default solar flux and accounting only
132 // for the eclipsing caused by the Earth.
133 let srp_dyn = SolarPressure::default(EARTH_J2000, almanac.clone())?;
134
135 // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
136 // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
137 let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
138
139 println!("{dynamics}");
140
141 // Finally, let's propagate this orbit to the same epoch as above.
142 // The first returned value is the spacecraft state at the final epoch.
143 // The second value is the full trajectory where the step size is variable step used by the propagator.
144 let (future_sc, trajectory) = Propagator::default(dynamics)
145 .with(sc, almanac.clone())
146 .until_epoch_with_traj(future_orbit_tb.epoch)?;
147
148 println!("=== High fidelity propagation ===");
149 println!(
150 "SMA changed by {:.3} km",
151 orbit.sma_km()? - future_sc.orbit.sma_km()?
152 );
153 println!(
154 "ECC changed by {:.6}",
155 orbit.ecc()? - future_sc.orbit.ecc()?
156 );
157 println!(
158 "INC changed by {:.3e} deg",
159 orbit.inc_deg()? - future_sc.orbit.inc_deg()?
160 );
161 println!(
162 "RAAN changed by {:.3} deg",
163 orbit.raan_deg()? - future_sc.orbit.raan_deg()?
164 );
165 println!(
166 "AOP changed by {:.3} deg",
167 orbit.aop_deg()? - future_sc.orbit.aop_deg()?
168 );
169 println!(
170 "TA changed by {:.3} deg",
171 orbit.ta_deg()? - future_sc.orbit.ta_deg()?
172 );
173
174 // We also have access to the full trajectory throughout the propagation.
175 println!("{trajectory}");
176
177 // With the trajectory, let's build a few data products.
178
179 // 1. Export the trajectory as a CCSDS OEM version 2.0 file and as a parquet file, which includes the Keplerian orbital elements.
180
181 trajectory.to_oem_file(
182 "./01_cubesat_hf_prop.oem",
183 ExportCfg::builder().step(Unit::Minute * 2).build(),
184 )?;
185
186 trajectory.to_parquet_with_cfg(
187 "./01_cubesat_hf_prop.parquet",
188 ExportCfg::builder().step(Unit::Minute * 2).build(),
189 almanac.clone(),
190 )?;
191
192 // 2. Compare the difference in the radial-intrack-crosstrack frame between the high fidelity
193 // and Keplerian propagation. The RIC frame is commonly used to compute the difference in position
194 // and velocity of different spacecraft.
195 // 3. Compute the azimuth, elevation, range, and range-rate data of that spacecraft as seen from Boulder, CO, USA.
196
197 let boulder_station = GroundStation::from_point(
198 "Boulder, CO, USA".to_string(),
199 40.014984, // latitude in degrees
200 -105.270546, // longitude in degrees
201 1.6550, // altitude in kilometers
202 almanac.frame_from_uid(IAU_EARTH_FRAME)?,
203 );
204
205 // We iterate over the trajectory, grabbing a state every two minutes.
206 let mut offset_s = vec![];
207 let mut epoch_str = vec![];
208 let mut ric_x_km = vec![];
209 let mut ric_y_km = vec![];
210 let mut ric_z_km = vec![];
211 let mut ric_vx_km_s = vec![];
212 let mut ric_vy_km_s = vec![];
213 let mut ric_vz_km_s = vec![];
214
215 let mut azimuth_deg = vec![];
216 let mut elevation_deg = vec![];
217 let mut range_km = vec![];
218 let mut range_rate_km_s = vec![];
219 for state in trajectory.every(Unit::Minute * 2) {
220 // Try to compute the Keplerian/two body state just in time.
221 // This method occasionally fails to converge on an appropriate true anomaly
222 // from the mean anomaly. If that happens, we just skip this state.
223 // The high fidelity and Keplerian states diverge continuously, and we're curious
224 // about the divergence in this quick analysis.
225 let this_epoch = state.epoch();
226 match orbit.at_epoch(this_epoch) {
227 Ok(tb_then) => {
228 offset_s.push((this_epoch - orbit.epoch).to_seconds());
229 epoch_str.push(format!("{this_epoch}"));
230 // Compute the two body state just in time.
231 let ric = state.orbit.ric_difference(&tb_then)?;
232 ric_x_km.push(ric.radius_km.x);
233 ric_y_km.push(ric.radius_km.y);
234 ric_z_km.push(ric.radius_km.z);
235 ric_vx_km_s.push(ric.velocity_km_s.x);
236 ric_vy_km_s.push(ric.velocity_km_s.y);
237 ric_vz_km_s.push(ric.velocity_km_s.z);
238
239 // Compute the AER data for each state.
240 let aer = almanac.azimuth_elevation_range_sez(
241 state.orbit,
242 boulder_station.to_orbit(this_epoch, &almanac)?,
243 None,
244 None,
245 )?;
246 azimuth_deg.push(aer.azimuth_deg);
247 elevation_deg.push(aer.elevation_deg);
248 range_km.push(aer.range_km);
249 range_rate_km_s.push(aer.range_rate_km_s);
250 }
251 Err(e) => warn!("{} {e}", state.epoch()),
252 };
253 }
254
255 // Build the data frames.
256 let ric_df = df!(
257 "Offset (s)" => offset_s.clone(),
258 "Epoch" => epoch_str.clone(),
259 "RIC X (km)" => ric_x_km,
260 "RIC Y (km)" => ric_y_km,
261 "RIC Z (km)" => ric_z_km,
262 "RIC VX (km/s)" => ric_vx_km_s,
263 "RIC VY (km/s)" => ric_vy_km_s,
264 "RIC VZ (km/s)" => ric_vz_km_s,
265 )?;
266
267 println!("RIC difference at start\n{}", ric_df.head(Some(10)));
268 println!("RIC difference at end\n{}", ric_df.tail(Some(10)));
269
270 let aer_df = df!(
271 "Offset (s)" => offset_s.clone(),
272 "Epoch" => epoch_str.clone(),
273 "azimuth (deg)" => azimuth_deg,
274 "elevation (deg)" => elevation_deg,
275 "range (km)" => range_km,
276 "range rate (km/s)" => range_rate_km_s,
277 )?;
278
279 // Finally, let's see when the spacecraft is visible, assuming 15 degrees minimum elevation.
280 let mask = aer_df
281 .column("elevation (deg)")?
282 .gt(&Column::Scalar(ScalarColumn::new(
283 "elevation mask (deg)".into(),
284 Scalar::new(DataType::Float64, AnyValue::Float64(15.0)),
285 offset_s.len(),
286 )))?;
287 let cubesat_visible = aer_df.filter(&mask)?;
288
289 println!("{cubesat_visible}");
290
291 Ok(())
292}
1.60.0 · Sourcepub fn new_cyclic<F>(data_fn: F) -> Arc<T>
pub fn new_cyclic<F>(data_fn: F) -> Arc<T>
Constructs a new Arc<T>
while giving you a Weak<T>
to the allocation,
to allow you to construct a T
which holds a weak pointer to itself.
Generally, a structure circularly referencing itself, either directly or
indirectly, should not hold a strong reference to itself to prevent a memory leak.
Using this function, you get access to the weak pointer during the
initialization of T
, before the Arc<T>
is created, such that you can
clone and store it inside the T
.
new_cyclic
first allocates the managed allocation for the Arc<T>
,
then calls your closure, giving it a Weak<T>
to this allocation,
and only afterwards completes the construction of the Arc<T>
by placing
the T
returned from your closure into the allocation.
Since the new Arc<T>
is not fully-constructed until Arc<T>::new_cyclic
returns, calling upgrade
on the weak reference inside your closure will
fail and result in a None
value.
§Panics
If data_fn
panics, the panic is propagated to the caller, and the
temporary Weak<T>
is dropped normally.
§Example
use std::sync::{Arc, Weak};
struct Gadget {
me: Weak<Gadget>,
}
impl Gadget {
/// Constructs a reference counted Gadget.
fn new() -> Arc<Self> {
// `me` is a `Weak<Gadget>` pointing at the new allocation of the
// `Arc` we're constructing.
Arc::new_cyclic(|me| {
// Create the actual struct here.
Gadget { me: me.clone() }
})
}
/// Returns a reference counted pointer to Self.
fn me(&self) -> Arc<Self> {
self.me.upgrade().unwrap()
}
}
1.82.0 · Sourcepub fn new_uninit() -> Arc<MaybeUninit<T>>
pub fn new_uninit() -> Arc<MaybeUninit<T>>
Constructs a new Arc
with uninitialized contents.
§Examples
#![feature(get_mut_unchecked)]
use std::sync::Arc;
let mut five = Arc::<u32>::new_uninit();
// Deferred initialization:
Arc::get_mut(&mut five).unwrap().write(5);
let five = unsafe { five.assume_init() };
assert_eq!(*five, 5)
Sourcepub fn new_zeroed() -> Arc<MaybeUninit<T>>
🔬This is a nightly-only experimental API. (new_zeroed_alloc
)
pub fn new_zeroed() -> Arc<MaybeUninit<T>>
new_zeroed_alloc
)Constructs a new Arc
with uninitialized contents, with the memory
being filled with 0
bytes.
See MaybeUninit::zeroed
for examples of correct and incorrect usage
of this method.
§Examples
#![feature(new_zeroed_alloc)]
use std::sync::Arc;
let zero = Arc::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };
assert_eq!(*zero, 0)
1.33.0 · Sourcepub fn pin(data: T) -> Pin<Arc<T>>
pub fn pin(data: T) -> Pin<Arc<T>>
Constructs a new Pin<Arc<T>>
. If T
does not implement Unpin
, then
data
will be pinned in memory and unable to be moved.
Sourcepub fn try_pin(data: T) -> Result<Pin<Arc<T>>, AllocError>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn try_pin(data: T) -> Result<Pin<Arc<T>>, AllocError>
allocator_api
)Constructs a new Pin<Arc<T>>
, return an error if allocation fails.
Sourcepub fn try_new(data: T) -> Result<Arc<T>, AllocError>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn try_new(data: T) -> Result<Arc<T>, AllocError>
allocator_api
)Constructs a new Arc<T>
, returning an error if allocation fails.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
let five = Arc::try_new(5)?;
Sourcepub fn try_new_uninit() -> Result<Arc<MaybeUninit<T>>, AllocError>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn try_new_uninit() -> Result<Arc<MaybeUninit<T>>, AllocError>
allocator_api
)Constructs a new Arc
with uninitialized contents, returning an error
if allocation fails.
§Examples
#![feature(allocator_api)]
#![feature(get_mut_unchecked)]
use std::sync::Arc;
let mut five = Arc::<u32>::try_new_uninit()?;
// Deferred initialization:
Arc::get_mut(&mut five).unwrap().write(5);
let five = unsafe { five.assume_init() };
assert_eq!(*five, 5);
Sourcepub fn try_new_zeroed() -> Result<Arc<MaybeUninit<T>>, AllocError>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn try_new_zeroed() -> Result<Arc<MaybeUninit<T>>, AllocError>
allocator_api
)Constructs a new Arc
with uninitialized contents, with the memory
being filled with 0
bytes, returning an error if allocation fails.
See MaybeUninit::zeroed
for examples of correct and incorrect usage
of this method.
§Examples
#![feature( allocator_api)]
use std::sync::Arc;
let zero = Arc::<u32>::try_new_zeroed()?;
let zero = unsafe { zero.assume_init() };
assert_eq!(*zero, 0);
Source§impl<T, A> Arc<T, A>where
A: Allocator,
impl<T, A> Arc<T, A>where
A: Allocator,
Sourcepub fn new_in(data: T, alloc: A) -> Arc<T, A>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn new_in(data: T, alloc: A) -> Arc<T, A>
allocator_api
)Constructs a new Arc<T>
in the provided allocator.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let five = Arc::new_in(5, System);
Sourcepub fn new_uninit_in(alloc: A) -> Arc<MaybeUninit<T>, A>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn new_uninit_in(alloc: A) -> Arc<MaybeUninit<T>, A>
allocator_api
)Constructs a new Arc
with uninitialized contents in the provided allocator.
§Examples
#![feature(get_mut_unchecked)]
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let mut five = Arc::<u32, _>::new_uninit_in(System);
let five = unsafe {
// Deferred initialization:
Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
five.assume_init()
};
assert_eq!(*five, 5)
Sourcepub fn new_zeroed_in(alloc: A) -> Arc<MaybeUninit<T>, A>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn new_zeroed_in(alloc: A) -> Arc<MaybeUninit<T>, A>
allocator_api
)Constructs a new Arc
with uninitialized contents, with the memory
being filled with 0
bytes, in the provided allocator.
See MaybeUninit::zeroed
for examples of correct and incorrect usage
of this method.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let zero = Arc::<u32, _>::new_zeroed_in(System);
let zero = unsafe { zero.assume_init() };
assert_eq!(*zero, 0)
Sourcepub fn new_cyclic_in<F>(data_fn: F, alloc: A) -> Arc<T, A>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn new_cyclic_in<F>(data_fn: F, alloc: A) -> Arc<T, A>
allocator_api
)Constructs a new Arc<T, A>
in the given allocator while giving you a Weak<T, A>
to the allocation,
to allow you to construct a T
which holds a weak pointer to itself.
Generally, a structure circularly referencing itself, either directly or
indirectly, should not hold a strong reference to itself to prevent a memory leak.
Using this function, you get access to the weak pointer during the
initialization of T
, before the Arc<T, A>
is created, such that you can
clone and store it inside the T
.
new_cyclic_in
first allocates the managed allocation for the Arc<T, A>
,
then calls your closure, giving it a Weak<T, A>
to this allocation,
and only afterwards completes the construction of the Arc<T, A>
by placing
the T
returned from your closure into the allocation.
Since the new Arc<T, A>
is not fully-constructed until Arc<T, A>::new_cyclic_in
returns, calling upgrade
on the weak reference inside your closure will
fail and result in a None
value.
§Panics
If data_fn
panics, the panic is propagated to the caller, and the
temporary Weak<T>
is dropped normally.
§Example
See new_cyclic
Sourcepub fn pin_in(data: T, alloc: A) -> Pin<Arc<T, A>>where
A: 'static,
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn pin_in(data: T, alloc: A) -> Pin<Arc<T, A>>where
A: 'static,
allocator_api
)Constructs a new Pin<Arc<T, A>>
in the provided allocator. If T
does not implement Unpin
,
then data
will be pinned in memory and unable to be moved.
Sourcepub fn try_pin_in(data: T, alloc: A) -> Result<Pin<Arc<T, A>>, AllocError>where
A: 'static,
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn try_pin_in(data: T, alloc: A) -> Result<Pin<Arc<T, A>>, AllocError>where
A: 'static,
allocator_api
)Constructs a new Pin<Arc<T, A>>
in the provided allocator, return an error if allocation
fails.
Sourcepub fn try_new_in(data: T, alloc: A) -> Result<Arc<T, A>, AllocError>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn try_new_in(data: T, alloc: A) -> Result<Arc<T, A>, AllocError>
allocator_api
)Constructs a new Arc<T, A>
in the provided allocator, returning an error if allocation fails.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let five = Arc::try_new_in(5, System)?;
Sourcepub fn try_new_uninit_in(alloc: A) -> Result<Arc<MaybeUninit<T>, A>, AllocError>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn try_new_uninit_in(alloc: A) -> Result<Arc<MaybeUninit<T>, A>, AllocError>
allocator_api
)Constructs a new Arc
with uninitialized contents, in the provided allocator, returning an
error if allocation fails.
§Examples
#![feature(allocator_api)]
#![feature(get_mut_unchecked)]
use std::sync::Arc;
use std::alloc::System;
let mut five = Arc::<u32, _>::try_new_uninit_in(System)?;
let five = unsafe {
// Deferred initialization:
Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
five.assume_init()
};
assert_eq!(*five, 5);
Sourcepub fn try_new_zeroed_in(alloc: A) -> Result<Arc<MaybeUninit<T>, A>, AllocError>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn try_new_zeroed_in(alloc: A) -> Result<Arc<MaybeUninit<T>, A>, AllocError>
allocator_api
)Constructs a new Arc
with uninitialized contents, with the memory
being filled with 0
bytes, in the provided allocator, returning an error if allocation
fails.
See MaybeUninit::zeroed
for examples of correct and incorrect usage
of this method.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let zero = Arc::<u32, _>::try_new_zeroed_in(System)?;
let zero = unsafe { zero.assume_init() };
assert_eq!(*zero, 0);
1.4.0 · Sourcepub fn try_unwrap(this: Arc<T, A>) -> Result<T, Arc<T, A>>
pub fn try_unwrap(this: Arc<T, A>) -> Result<T, Arc<T, A>>
Returns the inner value, if the Arc
has exactly one strong reference.
Otherwise, an Err
is returned with the same Arc
that was
passed in.
This will succeed even if there are outstanding weak references.
It is strongly recommended to use Arc::into_inner
instead if you don’t
keep the Arc
in the Err
case.
Immediately dropping the Err
-value, as the expression
Arc::try_unwrap(this).ok()
does, can cause the strong count to
drop to zero and the inner value of the Arc
to be dropped.
For instance, if two threads execute such an expression in parallel,
there is a race condition without the possibility of unsafety:
The threads could first both check whether they own the last instance
in Arc::try_unwrap
, determine that they both do not, and then both
discard and drop their instance in the call to ok
.
In this scenario, the value inside the Arc
is safely destroyed
by exactly one of the threads, but neither thread will ever be able
to use the value.
§Examples
use std::sync::Arc;
let x = Arc::new(3);
assert_eq!(Arc::try_unwrap(x), Ok(3));
let x = Arc::new(4);
let _y = Arc::clone(&x);
assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4);
1.70.0 · Sourcepub fn into_inner(this: Arc<T, A>) -> Option<T>
pub fn into_inner(this: Arc<T, A>) -> Option<T>
Returns the inner value, if the Arc
has exactly one strong reference.
Otherwise, None
is returned and the Arc
is dropped.
This will succeed even if there are outstanding weak references.
If Arc::into_inner
is called on every clone of this Arc
,
it is guaranteed that exactly one of the calls returns the inner value.
This means in particular that the inner value is not dropped.
Arc::try_unwrap
is conceptually similar to Arc::into_inner
, but it
is meant for different use-cases. If used as a direct replacement
for Arc::into_inner
anyway, such as with the expression
Arc::try_unwrap(this).ok()
, then it does
not give the same guarantee as described in the previous paragraph.
For more information, see the examples below and read the documentation
of Arc::try_unwrap
.
§Examples
Minimal example demonstrating the guarantee that Arc::into_inner
gives.
use std::sync::Arc;
let x = Arc::new(3);
let y = Arc::clone(&x);
// Two threads calling `Arc::into_inner` on both clones of an `Arc`:
let x_thread = std::thread::spawn(|| Arc::into_inner(x));
let y_thread = std::thread::spawn(|| Arc::into_inner(y));
let x_inner_value = x_thread.join().unwrap();
let y_inner_value = y_thread.join().unwrap();
// One of the threads is guaranteed to receive the inner value:
assert!(matches!(
(x_inner_value, y_inner_value),
(None, Some(3)) | (Some(3), None)
));
// The result could also be `(None, None)` if the threads called
// `Arc::try_unwrap(x).ok()` and `Arc::try_unwrap(y).ok()` instead.
A more practical example demonstrating the need for Arc::into_inner
:
use std::sync::Arc;
// Definition of a simple singly linked list using `Arc`:
#[derive(Clone)]
struct LinkedList<T>(Option<Arc<Node<T>>>);
struct Node<T>(T, Option<Arc<Node<T>>>);
// Dropping a long `LinkedList<T>` relying on the destructor of `Arc`
// can cause a stack overflow. To prevent this, we can provide a
// manual `Drop` implementation that does the destruction in a loop:
impl<T> Drop for LinkedList<T> {
fn drop(&mut self) {
let mut link = self.0.take();
while let Some(arc_node) = link.take() {
if let Some(Node(_value, next)) = Arc::into_inner(arc_node) {
link = next;
}
}
}
}
// Implementation of `new` and `push` omitted
impl<T> LinkedList<T> {
/* ... */
}
// The following code could have still caused a stack overflow
// despite the manual `Drop` impl if that `Drop` impl had used
// `Arc::try_unwrap(arc).ok()` instead of `Arc::into_inner(arc)`.
// Create a long list and clone it
let mut x = LinkedList::new();
let size = 100000;
for i in 0..size {
x.push(i); // Adds i to the front of x
}
let y = x.clone();
// Drop the clones in parallel
let x_thread = std::thread::spawn(|| drop(x));
let y_thread = std::thread::spawn(|| drop(y));
x_thread.join().unwrap();
y_thread.join().unwrap();
Source§impl<T> Arc<[T]>
impl<T> Arc<[T]>
1.82.0 · Sourcepub fn new_uninit_slice(len: usize) -> Arc<[MaybeUninit<T>]>
pub fn new_uninit_slice(len: usize) -> Arc<[MaybeUninit<T>]>
Constructs a new atomically reference-counted slice with uninitialized contents.
§Examples
#![feature(get_mut_unchecked)]
use std::sync::Arc;
let mut values = Arc::<[u32]>::new_uninit_slice(3);
// Deferred initialization:
let data = Arc::get_mut(&mut values).unwrap();
data[0].write(1);
data[1].write(2);
data[2].write(3);
let values = unsafe { values.assume_init() };
assert_eq!(*values, [1, 2, 3])
Sourcepub fn new_zeroed_slice(len: usize) -> Arc<[MaybeUninit<T>]>
🔬This is a nightly-only experimental API. (new_zeroed_alloc
)
pub fn new_zeroed_slice(len: usize) -> Arc<[MaybeUninit<T>]>
new_zeroed_alloc
)Constructs a new atomically reference-counted slice with uninitialized contents, with the memory being
filled with 0
bytes.
See MaybeUninit::zeroed
for examples of correct and
incorrect usage of this method.
§Examples
#![feature(new_zeroed_alloc)]
use std::sync::Arc;
let values = Arc::<[u32]>::new_zeroed_slice(3);
let values = unsafe { values.assume_init() };
assert_eq!(*values, [0, 0, 0])
Sourcepub fn into_array<const N: usize>(self) -> Option<Arc<[T; N]>>
🔬This is a nightly-only experimental API. (slice_as_array
)
pub fn into_array<const N: usize>(self) -> Option<Arc<[T; N]>>
slice_as_array
)Converts the reference-counted slice into a reference-counted array.
This operation does not reallocate; the underlying array of the slice is simply reinterpreted as an array type.
If N
is not exactly equal to the length of self
, then this method returns None
.
Source§impl<T, A> Arc<[T], A>where
A: Allocator,
impl<T, A> Arc<[T], A>where
A: Allocator,
Sourcepub fn new_uninit_slice_in(len: usize, alloc: A) -> Arc<[MaybeUninit<T>], A>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn new_uninit_slice_in(len: usize, alloc: A) -> Arc<[MaybeUninit<T>], A>
allocator_api
)Constructs a new atomically reference-counted slice with uninitialized contents in the provided allocator.
§Examples
#![feature(get_mut_unchecked)]
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let mut values = Arc::<[u32], _>::new_uninit_slice_in(3, System);
let values = unsafe {
// Deferred initialization:
Arc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
Arc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
Arc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3);
values.assume_init()
};
assert_eq!(*values, [1, 2, 3])
Sourcepub fn new_zeroed_slice_in(len: usize, alloc: A) -> Arc<[MaybeUninit<T>], A>
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Arc<[MaybeUninit<T>], A>
allocator_api
)Constructs a new atomically reference-counted slice with uninitialized contents, with the memory being
filled with 0
bytes, in the provided allocator.
See MaybeUninit::zeroed
for examples of correct and
incorrect usage of this method.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let values = Arc::<[u32], _>::new_zeroed_slice_in(3, System);
let values = unsafe { values.assume_init() };
assert_eq!(*values, [0, 0, 0])
Source§impl<T, A> Arc<MaybeUninit<T>, A>where
A: Allocator,
impl<T, A> Arc<MaybeUninit<T>, A>where
A: Allocator,
1.82.0 · Sourcepub unsafe fn assume_init(self) -> Arc<T, A>
pub unsafe fn assume_init(self) -> Arc<T, A>
Converts to Arc<T>
.
§Safety
As with MaybeUninit::assume_init
,
it is up to the caller to guarantee that the inner value
really is in an initialized state.
Calling this when the content is not yet fully initialized
causes immediate undefined behavior.
§Examples
#![feature(get_mut_unchecked)]
use std::sync::Arc;
let mut five = Arc::<u32>::new_uninit();
// Deferred initialization:
Arc::get_mut(&mut five).unwrap().write(5);
let five = unsafe { five.assume_init() };
assert_eq!(*five, 5)
Source§impl<T, A> Arc<[MaybeUninit<T>], A>where
A: Allocator,
impl<T, A> Arc<[MaybeUninit<T>], A>where
A: Allocator,
1.82.0 · Sourcepub unsafe fn assume_init(self) -> Arc<[T], A>
pub unsafe fn assume_init(self) -> Arc<[T], A>
Converts to Arc<[T]>
.
§Safety
As with MaybeUninit::assume_init
,
it is up to the caller to guarantee that the inner value
really is in an initialized state.
Calling this when the content is not yet fully initialized
causes immediate undefined behavior.
§Examples
#![feature(get_mut_unchecked)]
use std::sync::Arc;
let mut values = Arc::<[u32]>::new_uninit_slice(3);
// Deferred initialization:
let data = Arc::get_mut(&mut values).unwrap();
data[0].write(1);
data[1].write(2);
data[2].write(3);
let values = unsafe { values.assume_init() };
assert_eq!(*values, [1, 2, 3])
Source§impl<T> Arc<T>where
T: ?Sized,
impl<T> Arc<T>where
T: ?Sized,
1.17.0 · Sourcepub unsafe fn from_raw(ptr: *const T) -> Arc<T>
pub unsafe fn from_raw(ptr: *const T) -> Arc<T>
Constructs an Arc<T>
from a raw pointer.
The raw pointer must have been previously returned by a call to
Arc<U>::into_raw
with the following requirements:
- If
U
is sized, it must have the same size and alignment asT
. This is trivially true ifU
isT
. - If
U
is unsized, its data pointer must have the same size and alignment asT
. This is trivially true ifArc<U>
was constructed throughArc<T>
and then converted toArc<U>
through an unsized coercion.
Note that if U
or U
’s data pointer is not T
but has the same size
and alignment, this is basically like transmuting references of
different types. See mem::transmute
for more information
on what restrictions apply in this case.
The raw pointer must point to a block of memory allocated by the global allocator.
The user of from_raw
has to make sure a specific value of T
is only
dropped once.
This function is unsafe because improper use may lead to memory unsafety,
even if the returned Arc<T>
is never accessed.
§Examples
use std::sync::Arc;
let x = Arc::new("hello".to_owned());
let x_ptr = Arc::into_raw(x);
unsafe {
// Convert back to an `Arc` to prevent leak.
let x = Arc::from_raw(x_ptr);
assert_eq!(&*x, "hello");
// Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.
}
// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!
Convert a slice back into its original array:
use std::sync::Arc;
let x: Arc<[u32]> = Arc::new([1, 2, 3]);
let x_ptr: *const [u32] = Arc::into_raw(x);
unsafe {
let x: Arc<[u32; 3]> = Arc::from_raw(x_ptr.cast::<[u32; 3]>());
assert_eq!(&*x, &[1, 2, 3]);
}
1.17.0 · Sourcepub fn into_raw(this: Arc<T>) -> *const T
pub fn into_raw(this: Arc<T>) -> *const T
Consumes the Arc
, returning the wrapped pointer.
To avoid a memory leak the pointer must be converted back to an Arc
using
Arc::from_raw
.
§Examples
use std::sync::Arc;
let x = Arc::new("hello".to_owned());
let x_ptr = Arc::into_raw(x);
assert_eq!(unsafe { &*x_ptr }, "hello");
1.51.0 · Sourcepub unsafe fn increment_strong_count(ptr: *const T)
pub unsafe fn increment_strong_count(ptr: *const T)
Increments the strong reference count on the Arc<T>
associated with the
provided pointer by one.
§Safety
The pointer must have been obtained through Arc::into_raw
and must satisfy the
same layout requirements specified in Arc::from_raw_in
.
The associated Arc
instance must be valid (i.e. the strong count must be at
least 1) for the duration of this method, and ptr
must point to a block of memory
allocated by the global allocator.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
unsafe {
let ptr = Arc::into_raw(five);
Arc::increment_strong_count(ptr);
// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
let five = Arc::from_raw(ptr);
assert_eq!(2, Arc::strong_count(&five));
}
1.51.0 · Sourcepub unsafe fn decrement_strong_count(ptr: *const T)
pub unsafe fn decrement_strong_count(ptr: *const T)
Decrements the strong reference count on the Arc<T>
associated with the
provided pointer by one.
§Safety
The pointer must have been obtained through Arc::into_raw
and must satisfy the
same layout requirements specified in Arc::from_raw_in
.
The associated Arc
instance must be valid (i.e. the strong count must be at
least 1) when invoking this method, and ptr
must point to a block of memory
allocated by the global allocator. This method can be used to release the final
Arc
and backing storage, but should not be called after the final Arc
has been
released.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
unsafe {
let ptr = Arc::into_raw(five);
Arc::increment_strong_count(ptr);
// Those assertions are deterministic because we haven't shared
// the `Arc` between threads.
let five = Arc::from_raw(ptr);
assert_eq!(2, Arc::strong_count(&five));
Arc::decrement_strong_count(ptr);
assert_eq!(1, Arc::strong_count(&five));
}
Source§impl<T, A> Arc<T, A>
impl<T, A> Arc<T, A>
Sourcepub fn allocator(this: &Arc<T, A>) -> &A
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn allocator(this: &Arc<T, A>) -> &A
allocator_api
)Returns a reference to the underlying allocator.
Note: this is an associated function, which means that you have
to call it as Arc::allocator(&a)
instead of a.allocator()
. This
is so that there is no conflict with a method on the inner type.
Sourcepub fn into_raw_with_allocator(this: Arc<T, A>) -> (*const T, A)
🔬This is a nightly-only experimental API. (allocator_api
)
pub fn into_raw_with_allocator(this: Arc<T, A>) -> (*const T, A)
allocator_api
)Consumes the Arc
, returning the wrapped pointer and allocator.
To avoid a memory leak the pointer must be converted back to an Arc
using
Arc::from_raw_in
.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let x = Arc::new_in("hello".to_owned(), System);
let (ptr, alloc) = Arc::into_raw_with_allocator(x);
assert_eq!(unsafe { &*ptr }, "hello");
let x = unsafe { Arc::from_raw_in(ptr, alloc) };
assert_eq!(&*x, "hello");
1.45.0 · Sourcepub fn as_ptr(this: &Arc<T, A>) -> *const T
pub fn as_ptr(this: &Arc<T, A>) -> *const T
Provides a raw pointer to the data.
The counts are not affected in any way and the Arc
is not consumed. The pointer is valid for
as long as there are strong counts in the Arc
.
§Examples
use std::sync::Arc;
let x = Arc::new("hello".to_owned());
let y = Arc::clone(&x);
let x_ptr = Arc::as_ptr(&x);
assert_eq!(x_ptr, Arc::as_ptr(&y));
assert_eq!(unsafe { &*x_ptr }, "hello");
Sourcepub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Arc<T, A>
🔬This is a nightly-only experimental API. (allocator_api
)
pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Arc<T, A>
allocator_api
)Constructs an Arc<T, A>
from a raw pointer.
The raw pointer must have been previously returned by a call to Arc<U, A>::into_raw
with the following requirements:
- If
U
is sized, it must have the same size and alignment asT
. This is trivially true ifU
isT
. - If
U
is unsized, its data pointer must have the same size and alignment asT
. This is trivially true ifArc<U>
was constructed throughArc<T>
and then converted toArc<U>
through an unsized coercion.
Note that if U
or U
’s data pointer is not T
but has the same size
and alignment, this is basically like transmuting references of
different types. See mem::transmute
for more information
on what restrictions apply in this case.
The raw pointer must point to a block of memory allocated by alloc
The user of from_raw
has to make sure a specific value of T
is only
dropped once.
This function is unsafe because improper use may lead to memory unsafety,
even if the returned Arc<T>
is never accessed.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let x = Arc::new_in("hello".to_owned(), System);
let (x_ptr, alloc) = Arc::into_raw_with_allocator(x);
unsafe {
// Convert back to an `Arc` to prevent leak.
let x = Arc::from_raw_in(x_ptr, System);
assert_eq!(&*x, "hello");
// Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.
}
// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!
Convert a slice back into its original array:
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let x: Arc<[u32], _> = Arc::new_in([1, 2, 3], System);
let x_ptr: *const [u32] = Arc::into_raw_with_allocator(x).0;
unsafe {
let x: Arc<[u32; 3], _> = Arc::from_raw_in(x_ptr.cast::<[u32; 3]>(), System);
assert_eq!(&*x, &[1, 2, 3]);
}
1.15.0 · Sourcepub fn weak_count(this: &Arc<T, A>) -> usize
pub fn weak_count(this: &Arc<T, A>) -> usize
Gets the number of Weak
pointers to this allocation.
§Safety
This method by itself is safe, but using it correctly requires extra care. Another thread can change the weak count at any time, including potentially between calling this method and acting on the result.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
let _weak_five = Arc::downgrade(&five);
// This assertion is deterministic because we haven't shared
// the `Arc` or `Weak` between threads.
assert_eq!(1, Arc::weak_count(&five));
1.15.0 · Sourcepub fn strong_count(this: &Arc<T, A>) -> usize
pub fn strong_count(this: &Arc<T, A>) -> usize
Gets the number of strong (Arc
) pointers to this allocation.
§Safety
This method by itself is safe, but using it correctly requires extra care. Another thread can change the strong count at any time, including potentially between calling this method and acting on the result.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
let _also_five = Arc::clone(&five);
// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
assert_eq!(2, Arc::strong_count(&five));
Sourcepub unsafe fn increment_strong_count_in(ptr: *const T, alloc: A)where
A: Clone,
🔬This is a nightly-only experimental API. (allocator_api
)
pub unsafe fn increment_strong_count_in(ptr: *const T, alloc: A)where
A: Clone,
allocator_api
)Increments the strong reference count on the Arc<T>
associated with the
provided pointer by one.
§Safety
The pointer must have been obtained through Arc::into_raw
and must satisfy the
same layout requirements specified in Arc::from_raw_in
.
The associated Arc
instance must be valid (i.e. the strong count must be at
least 1) for the duration of this method, and ptr
must point to a block of memory
allocated by alloc
.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let five = Arc::new_in(5, System);
unsafe {
let (ptr, _alloc) = Arc::into_raw_with_allocator(five);
Arc::increment_strong_count_in(ptr, System);
// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
let five = Arc::from_raw_in(ptr, System);
assert_eq!(2, Arc::strong_count(&five));
}
Sourcepub unsafe fn decrement_strong_count_in(ptr: *const T, alloc: A)
🔬This is a nightly-only experimental API. (allocator_api
)
pub unsafe fn decrement_strong_count_in(ptr: *const T, alloc: A)
allocator_api
)Decrements the strong reference count on the Arc<T>
associated with the
provided pointer by one.
§Safety
The pointer must have been obtained through Arc::into_raw
and must satisfy the
same layout requirements specified in Arc::from_raw_in
.
The associated Arc
instance must be valid (i.e. the strong count must be at
least 1) when invoking this method, and ptr
must point to a block of memory
allocated by alloc
. This method can be used to release the final
Arc
and backing storage, but should not be called after the final Arc
has been
released.
§Examples
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;
let five = Arc::new_in(5, System);
unsafe {
let (ptr, _alloc) = Arc::into_raw_with_allocator(five);
Arc::increment_strong_count_in(ptr, System);
// Those assertions are deterministic because we haven't shared
// the `Arc` between threads.
let five = Arc::from_raw_in(ptr, System);
assert_eq!(2, Arc::strong_count(&five));
Arc::decrement_strong_count_in(ptr, System);
assert_eq!(1, Arc::strong_count(&five));
}
1.17.0 · Sourcepub fn ptr_eq(this: &Arc<T, A>, other: &Arc<T, A>) -> bool
pub fn ptr_eq(this: &Arc<T, A>, other: &Arc<T, A>) -> bool
Returns true
if the two Arc
s point to the same allocation in a vein similar to
ptr::eq
. This function ignores the metadata of dyn Trait
pointers.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
let same_five = Arc::clone(&five);
let other_five = Arc::new(5);
assert!(Arc::ptr_eq(&five, &same_five));
assert!(!Arc::ptr_eq(&five, &other_five));
Source§impl<T, A> Arc<T, A>
impl<T, A> Arc<T, A>
1.4.0 · Sourcepub fn make_mut(this: &mut Arc<T, A>) -> &mut T
pub fn make_mut(this: &mut Arc<T, A>) -> &mut T
Makes a mutable reference into the given Arc
.
If there are other Arc
pointers to the same allocation, then make_mut
will
clone
the inner value to a new allocation to ensure unique ownership. This is also
referred to as clone-on-write.
However, if there are no other Arc
pointers to this allocation, but some Weak
pointers, then the Weak
pointers will be dissociated and the inner value will not
be cloned.
See also get_mut
, which will fail rather than cloning the inner value
or dissociating Weak
pointers.
§Examples
use std::sync::Arc;
let mut data = Arc::new(5);
*Arc::make_mut(&mut data) += 1; // Won't clone anything
let mut other_data = Arc::clone(&data); // Won't clone inner data
*Arc::make_mut(&mut data) += 1; // Clones inner data
*Arc::make_mut(&mut data) += 1; // Won't clone anything
*Arc::make_mut(&mut other_data) *= 2; // Won't clone anything
// Now `data` and `other_data` point to different allocations.
assert_eq!(*data, 8);
assert_eq!(*other_data, 12);
Weak
pointers will be dissociated:
use std::sync::Arc;
let mut data = Arc::new(75);
let weak = Arc::downgrade(&data);
assert!(75 == *data);
assert!(75 == *weak.upgrade().unwrap());
*Arc::make_mut(&mut data) += 1;
assert!(76 == *data);
assert!(weak.upgrade().is_none());
Source§impl<T, A> Arc<T, A>
impl<T, A> Arc<T, A>
1.76.0 · Sourcepub fn unwrap_or_clone(this: Arc<T, A>) -> T
pub fn unwrap_or_clone(this: Arc<T, A>) -> T
If we have the only reference to T
then unwrap it. Otherwise, clone T
and return the
clone.
Assuming arc_t
is of type Arc<T>
, this function is functionally equivalent to
(*arc_t).clone()
, but will avoid cloning the inner value where possible.
§Examples
let inner = String::from("test");
let ptr = inner.as_ptr();
let arc = Arc::new(inner);
let inner = Arc::unwrap_or_clone(arc);
// The inner value was not cloned
assert!(ptr::eq(ptr, inner.as_ptr()));
let arc = Arc::new(inner);
let arc2 = arc.clone();
let inner = Arc::unwrap_or_clone(arc);
// Because there were 2 references, we had to clone the inner value.
assert!(!ptr::eq(ptr, inner.as_ptr()));
// `arc2` is the last reference, so when we unwrap it we get back
// the original `String`.
let inner = Arc::unwrap_or_clone(arc2);
assert!(ptr::eq(ptr, inner.as_ptr()));
Source§impl<T, A> Arc<T, A>
impl<T, A> Arc<T, A>
1.4.0 · Sourcepub fn get_mut(this: &mut Arc<T, A>) -> Option<&mut T>
pub fn get_mut(this: &mut Arc<T, A>) -> Option<&mut T>
Returns a mutable reference into the given Arc
, if there are
no other Arc
or Weak
pointers to the same allocation.
Returns None
otherwise, because it is not safe to
mutate a shared value.
See also make_mut
, which will clone
the inner value when there are other Arc
pointers.
§Examples
use std::sync::Arc;
let mut x = Arc::new(3);
*Arc::get_mut(&mut x).unwrap() = 4;
assert_eq!(*x, 4);
let _y = Arc::clone(&x);
assert!(Arc::get_mut(&mut x).is_none());
Sourcepub unsafe fn get_mut_unchecked(this: &mut Arc<T, A>) -> &mut T
🔬This is a nightly-only experimental API. (get_mut_unchecked
)
pub unsafe fn get_mut_unchecked(this: &mut Arc<T, A>) -> &mut T
get_mut_unchecked
)Returns a mutable reference into the given Arc
,
without any check.
See also get_mut
, which is safe and does appropriate checks.
§Safety
If any other Arc
or Weak
pointers to the same allocation exist, then
they must not be dereferenced or have active borrows for the duration
of the returned borrow, and their inner type must be exactly the same as the
inner type of this Rc (including lifetimes). This is trivially the case if no
such pointers exist, for example immediately after Arc::new
.
§Examples
#![feature(get_mut_unchecked)]
use std::sync::Arc;
let mut x = Arc::new(String::new());
unsafe {
Arc::get_mut_unchecked(&mut x).push_str("foo")
}
assert_eq!(*x, "foo");
Other Arc
pointers to the same allocation must be to the same type.
#![feature(get_mut_unchecked)]
use std::sync::Arc;
let x: Arc<str> = Arc::from("Hello, world!");
let mut y: Arc<[u8]> = x.clone().into();
unsafe {
// this is Undefined Behavior, because x's inner type is str, not [u8]
Arc::get_mut_unchecked(&mut y).fill(0xff); // 0xff is invalid in UTF-8
}
println!("{}", &*x); // Invalid UTF-8 in a str
Other Arc
pointers to the same allocation must be to the exact same type, including lifetimes.
#![feature(get_mut_unchecked)]
use std::sync::Arc;
let x: Arc<&str> = Arc::new("Hello, world!");
{
let s = String::from("Oh, no!");
let mut y: Arc<&str> = x.clone();
unsafe {
// this is Undefined Behavior, because x's inner type
// is &'long str, not &'short str
*Arc::get_mut_unchecked(&mut y) = &s;
}
}
println!("{}", &*x); // Use-after-free
Sourcepub fn is_unique(this: &Arc<T, A>) -> bool
🔬This is a nightly-only experimental API. (arc_is_unique
)
pub fn is_unique(this: &Arc<T, A>) -> bool
arc_is_unique
)Determine whether this is the unique reference to the underlying data.
Returns true
if there are no other Arc
or Weak
pointers to the same allocation;
returns false
otherwise.
If this function returns true
, then is guaranteed to be safe to call get_mut_unchecked
on this Arc
, so long as no clones occur in between.
§Examples
#![feature(arc_is_unique)]
use std::sync::Arc;
let x = Arc::new(3);
assert!(Arc::is_unique(&x));
let y = Arc::clone(&x);
assert!(!Arc::is_unique(&x));
drop(y);
// Weak references also count, because they could be upgraded at any time.
let z = Arc::downgrade(&x);
assert!(!Arc::is_unique(&x));
§Pointer invalidation
This function will always return the same value as Arc::get_mut(arc).is_some()
. However,
unlike that operation it does not produce any mutable references to the underlying data,
meaning no pointers to the data inside the Arc
are invalidated by the call. Thus, the
following code is valid, even though it would be UB if it used Arc::get_mut
:
#![feature(arc_is_unique)]
use std::sync::Arc;
let arc = Arc::new(5);
let pointer: *const i32 = &*arc;
assert!(Arc::is_unique(&arc));
assert_eq!(unsafe { *pointer }, 5);
§Atomic orderings
Concurrent drops to other Arc
pointers to the same allocation will synchronize with this
call - that is, this call performs an Acquire
operation on the underlying strong and weak
ref counts. This ensures that calling get_mut_unchecked
is safe.
Note that this operation requires locking the weak ref count, so concurrent calls to
downgrade
may spin-loop for a short period of time.
Source§impl<A> Arc<dyn Any + Sync + Send, A>where
A: Allocator,
impl<A> Arc<dyn Any + Sync + Send, A>where
A: Allocator,
1.29.0 · Sourcepub fn downcast<T>(self) -> Result<Arc<T, A>, Arc<dyn Any + Sync + Send, A>>
pub fn downcast<T>(self) -> Result<Arc<T, A>, Arc<dyn Any + Sync + Send, A>>
Attempts to downcast the Arc<dyn Any + Send + Sync>
to a concrete type.
§Examples
use std::any::Any;
use std::sync::Arc;
fn print_if_string(value: Arc<dyn Any + Send + Sync>) {
if let Ok(string) = value.downcast::<String>() {
println!("String ({}): {}", string.len(), string);
}
}
let my_string = "Hello World".to_string();
print_if_string(Arc::new(my_string));
print_if_string(Arc::new(0i8));
Sourcepub unsafe fn downcast_unchecked<T>(self) -> Arc<T, A>
🔬This is a nightly-only experimental API. (downcast_unchecked
)
pub unsafe fn downcast_unchecked<T>(self) -> Arc<T, A>
downcast_unchecked
)Downcasts the Arc<dyn Any + Send + Sync>
to a concrete type.
For a safe alternative see downcast
.
§Examples
#![feature(downcast_unchecked)]
use std::any::Any;
use std::sync::Arc;
let x: Arc<dyn Any + Send + Sync> = Arc::new(1_usize);
unsafe {
assert_eq!(*x.downcast_unchecked::<usize>(), 1);
}
§Safety
The contained value must be of type T
. Calling this method
with the incorrect type is undefined behavior.
Trait Implementations§
§impl Array for Arc<dyn Array>
Ergonomics: Allow use of an ArrayRef as an &dyn Array
impl Array for Arc<dyn Array>
Ergonomics: Allow use of an ArrayRef as an &dyn Array
§fn shrink_to_fit(&mut self)
fn shrink_to_fit(&mut self)
For shared buffers, this is a no-op.
§fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
§fn offset(&self) -> usize
fn offset(&self) -> usize
0
. Read more§fn logical_nulls(&self) -> Option<NullBuffer>
fn logical_nulls(&self) -> Option<NullBuffer>
NullBuffer
] that represents the logical
null values of this array, if any. Read more§fn null_count(&self) -> usize
fn null_count(&self) -> usize
§fn logical_null_count(&self) -> usize
fn logical_null_count(&self) -> usize
§fn is_nullable(&self) -> bool
fn is_nullable(&self) -> bool
false
if the array is guaranteed to not contain any logical nulls Read more§fn get_buffer_memory_size(&self) -> usize
fn get_buffer_memory_size(&self) -> usize
§fn get_array_memory_size(&self) -> usize
fn get_array_memory_size(&self) -> usize
get_buffer_memory_size()
and
includes the overhead of the data structures that contain the pointers to the various buffers.§impl AsArray for Arc<dyn Array>
impl AsArray for Arc<dyn Array>
§fn as_boolean_opt(&self) -> Option<&BooleanArray>
fn as_boolean_opt(&self) -> Option<&BooleanArray>
BooleanArray
] returning None
if not possible§fn as_primitive_opt<T>(&self) -> Option<&PrimitiveArray<T>>where
T: ArrowPrimitiveType,
fn as_primitive_opt<T>(&self) -> Option<&PrimitiveArray<T>>where
T: ArrowPrimitiveType,
PrimitiveArray
] returning None
if not possible§fn as_bytes_opt<T>(&self) -> Option<&GenericByteArray<T>>where
T: ByteArrayType,
fn as_bytes_opt<T>(&self) -> Option<&GenericByteArray<T>>where
T: ByteArrayType,
GenericByteArray
] returning None
if not possible§fn as_byte_view_opt<T>(&self) -> Option<&GenericByteViewArray<T>>where
T: ByteViewType,
fn as_byte_view_opt<T>(&self) -> Option<&GenericByteViewArray<T>>where
T: ByteViewType,
GenericByteViewArray
] returning None
if not possible§fn as_struct_opt(&self) -> Option<&StructArray>
fn as_struct_opt(&self) -> Option<&StructArray>
StructArray
] returning None
if not possible§fn as_union_opt(&self) -> Option<&UnionArray>
fn as_union_opt(&self) -> Option<&UnionArray>
UnionArray
] returning None
if not possible§fn as_list_opt<O>(&self) -> Option<&GenericListArray<O>>where
O: OffsetSizeTrait,
fn as_list_opt<O>(&self) -> Option<&GenericListArray<O>>where
O: OffsetSizeTrait,
GenericListArray
] returning None
if not possible§fn as_list_view_opt<O>(&self) -> Option<&GenericListViewArray<O>>where
O: OffsetSizeTrait,
fn as_list_view_opt<O>(&self) -> Option<&GenericListViewArray<O>>where
O: OffsetSizeTrait,
GenericListViewArray
] returning None
if not possible§fn as_fixed_size_binary_opt(&self) -> Option<&FixedSizeBinaryArray>
fn as_fixed_size_binary_opt(&self) -> Option<&FixedSizeBinaryArray>
FixedSizeBinaryArray
] returning None
if not possible§fn as_fixed_size_list_opt(&self) -> Option<&FixedSizeListArray>
fn as_fixed_size_list_opt(&self) -> Option<&FixedSizeListArray>
FixedSizeListArray
] returning None
if not possible§fn as_map_opt(&self) -> Option<&MapArray>
fn as_map_opt(&self) -> Option<&MapArray>
MapArray
] returning None
if not possible§fn as_dictionary_opt<K>(&self) -> Option<&DictionaryArray<K>>where
K: ArrowDictionaryKeyType,
fn as_dictionary_opt<K>(&self) -> Option<&DictionaryArray<K>>where
K: ArrowDictionaryKeyType,
DictionaryArray
] returning None
if not possible§fn as_any_dictionary_opt(&self) -> Option<&dyn AnyDictionaryArray>
fn as_any_dictionary_opt(&self) -> Option<&dyn AnyDictionaryArray>
AnyDictionaryArray
] returning None
if not possible§fn as_run_opt<K>(&self) -> Option<&RunArray<K>>where
K: RunEndIndexType,
fn as_run_opt<K>(&self) -> Option<&RunArray<K>>where
K: RunEndIndexType,
RunArray
] returning None
if not possible§fn as_string_opt<O>(&self) -> Option<&GenericByteArray<GenericStringType<O>>>where
O: OffsetSizeTrait,
fn as_string_opt<O>(&self) -> Option<&GenericByteArray<GenericStringType<O>>>where
O: OffsetSizeTrait,
GenericStringArray
] returning None
if not possible§fn as_boolean(&self) -> &BooleanArray
fn as_boolean(&self) -> &BooleanArray
BooleanArray
] panicking if not possible§fn as_primitive<T>(&self) -> &PrimitiveArray<T>where
T: ArrowPrimitiveType,
fn as_primitive<T>(&self) -> &PrimitiveArray<T>where
T: ArrowPrimitiveType,
PrimitiveArray
] panicking if not possible§fn as_bytes<T>(&self) -> &GenericByteArray<T>where
T: ByteArrayType,
fn as_bytes<T>(&self) -> &GenericByteArray<T>where
T: ByteArrayType,
GenericByteArray
] panicking if not possible§fn as_string<O>(&self) -> &GenericByteArray<GenericStringType<O>>where
O: OffsetSizeTrait,
fn as_string<O>(&self) -> &GenericByteArray<GenericStringType<O>>where
O: OffsetSizeTrait,
GenericStringArray
] panicking if not possible§fn as_binary_opt<O>(&self) -> Option<&GenericByteArray<GenericBinaryType<O>>>where
O: OffsetSizeTrait,
fn as_binary_opt<O>(&self) -> Option<&GenericByteArray<GenericBinaryType<O>>>where
O: OffsetSizeTrait,
GenericBinaryArray
] returning None
if not possible§fn as_binary<O>(&self) -> &GenericByteArray<GenericBinaryType<O>>where
O: OffsetSizeTrait,
fn as_binary<O>(&self) -> &GenericByteArray<GenericBinaryType<O>>where
O: OffsetSizeTrait,
GenericBinaryArray
] panicking if not possible§fn as_string_view_opt(&self) -> Option<&GenericByteViewArray<StringViewType>>
fn as_string_view_opt(&self) -> Option<&GenericByteViewArray<StringViewType>>
StringViewArray
] returning None
if not possible§fn as_string_view(&self) -> &GenericByteViewArray<StringViewType>
fn as_string_view(&self) -> &GenericByteViewArray<StringViewType>
StringViewArray
] panicking if not possible§fn as_binary_view_opt(&self) -> Option<&GenericByteViewArray<BinaryViewType>>
fn as_binary_view_opt(&self) -> Option<&GenericByteViewArray<BinaryViewType>>
BinaryViewArray
] returning None
if not possible§fn as_binary_view(&self) -> &GenericByteViewArray<BinaryViewType>
fn as_binary_view(&self) -> &GenericByteViewArray<BinaryViewType>
BinaryViewArray
] panicking if not possible§fn as_byte_view<T>(&self) -> &GenericByteViewArray<T>where
T: ByteViewType,
fn as_byte_view<T>(&self) -> &GenericByteViewArray<T>where
T: ByteViewType,
GenericByteViewArray
] panicking if not possible§fn as_list<O>(&self) -> &GenericListArray<O>where
O: OffsetSizeTrait,
fn as_list<O>(&self) -> &GenericListArray<O>where
O: OffsetSizeTrait,
GenericListArray
] panicking if not possible§fn as_list_view<O>(&self) -> &GenericListViewArray<O>where
O: OffsetSizeTrait,
fn as_list_view<O>(&self) -> &GenericListViewArray<O>where
O: OffsetSizeTrait,
GenericListViewArray
] panicking if not possible§fn as_fixed_size_binary(&self) -> &FixedSizeBinaryArray
fn as_fixed_size_binary(&self) -> &FixedSizeBinaryArray
FixedSizeBinaryArray
] panicking if not possible§fn as_fixed_size_list(&self) -> &FixedSizeListArray
fn as_fixed_size_list(&self) -> &FixedSizeListArray
FixedSizeListArray
] panicking if not possible§fn as_dictionary<K>(&self) -> &DictionaryArray<K>where
K: ArrowDictionaryKeyType,
fn as_dictionary<K>(&self) -> &DictionaryArray<K>where
K: ArrowDictionaryKeyType,
DictionaryArray
] panicking if not possible§fn as_run<K>(&self) -> &RunArray<K>where
K: RunEndIndexType,
fn as_run<K>(&self) -> &RunArray<K>where
K: RunEndIndexType,
RunArray
] panicking if not possible§fn as_any_dictionary(&self) -> &dyn AnyDictionaryArray
fn as_any_dictionary(&self) -> &dyn AnyDictionaryArray
AnyDictionaryArray
] panicking if not possible§impl<T> AsBacktrace for Arc<T>where
T: AsBacktrace,
impl<T> AsBacktrace for Arc<T>where
T: AsBacktrace,
§fn as_backtrace(&self) -> Option<&Backtrace>
fn as_backtrace(&self) -> Option<&Backtrace>
1.64.0 · Source§impl<T> AsFd for Arc<T>
This impl allows implementing traits that require AsFd
on Arc.
impl<T> AsFd for Arc<T>
This impl allows implementing traits that require AsFd
on Arc.
use std::net::UdpSocket;
use std::sync::Arc;
trait MyTrait: AsFd {}
impl MyTrait for Arc<UdpSocket> {}
impl MyTrait for Box<UdpSocket> {}
Source§fn as_fd(&self) -> BorrowedFd<'_>
fn as_fd(&self) -> BorrowedFd<'_>
1.63.0 · Source§impl<T> AsRawFd for Arc<T>where
T: AsRawFd,
This impl allows implementing traits that require AsRawFd
on Arc.
impl<T> AsRawFd for Arc<T>where
T: AsRawFd,
This impl allows implementing traits that require AsRawFd
on Arc.
use std::net::UdpSocket;
use std::sync::Arc;
trait MyTrait: AsRawFd {
}
impl MyTrait for Arc<UdpSocket> {}
impl MyTrait for Box<UdpSocket> {}
1.0.0 · Source§impl<T, A> Clone for Arc<T, A>
impl<T, A> Clone for Arc<T, A>
Source§fn clone(&self) -> Arc<T, A>
fn clone(&self) -> Arc<T, A>
Makes a clone of the Arc
pointer.
This creates another pointer to the same allocation, increasing the strong reference count.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
let _ = Arc::clone(&five);
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more1.0.0 · Source§impl<T, A> Drop for Arc<T, A>
impl<T, A> Drop for Arc<T, A>
Source§fn drop(&mut self)
fn drop(&mut self)
Drops the Arc
.
This will decrement the strong reference count. If the strong reference
count reaches zero then the only other references (if any) are
Weak
, so we drop
the inner value.
§Examples
use std::sync::Arc;
struct Foo;
impl Drop for Foo {
fn drop(&mut self) {
println!("dropped!");
}
}
let foo = Arc::new(Foo);
let foo2 = Arc::clone(&foo);
drop(foo); // Doesn't print anything
drop(foo2); // Prints "dropped!"
1.52.0 · Source§impl<T> Error for Arc<T>
impl<T> Error for Arc<T>
Source§fn description(&self) -> &str
fn description(&self) -> &str
Source§fn cause(&self) -> Option<&dyn Error>
fn cause(&self) -> Option<&dyn Error>
1.37.0 · Source§impl<T> FromIterator<T> for Arc<[T]>
impl<T> FromIterator<T> for Arc<[T]>
Source§fn from_iter<I>(iter: I) -> Arc<[T]>where
I: IntoIterator<Item = T>,
fn from_iter<I>(iter: I) -> Arc<[T]>where
I: IntoIterator<Item = T>,
Takes each element in the Iterator
and collects it into an Arc<[T]>
.
§Performance characteristics
§The general case
In the general case, collecting into Arc<[T]>
is done by first
collecting into a Vec<T>
. That is, when writing the following:
let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect();
this behaves as if we wrote:
let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0)
.collect::<Vec<_>>() // The first set of allocations happens here.
.into(); // A second allocation for `Arc<[T]>` happens here.
This will allocate as many times as needed for constructing the Vec<T>
and then it will allocate once for turning the Vec<T>
into the Arc<[T]>
.
§Iterators of known length
When your Iterator
implements TrustedLen
and is of an exact size,
a single allocation will be made for the Arc<[T]>
. For example:
let evens: Arc<[u8]> = (0..10).collect(); // Just a single allocation happens here.
§impl<T> FromParallelIterator<T> for Arc<[T]>where
T: Send,
Collects items from a parallel iterator into an atomically-reference-counted slice.
impl<T> FromParallelIterator<T> for Arc<[T]>where
T: Send,
Collects items from a parallel iterator into an atomically-reference-counted slice.
§fn from_par_iter<I>(par_iter: I) -> Arc<[T]>where
I: IntoParallelIterator<Item = T>,
fn from_par_iter<I>(par_iter: I) -> Arc<[T]>where
I: IntoParallelIterator<Item = T>,
par_iter
. Read more1.0.0 · Source§impl<T, A> Ord for Arc<T, A>
impl<T, A> Ord for Arc<T, A>
Source§fn cmp(&self, other: &Arc<T, A>) -> Ordering
fn cmp(&self, other: &Arc<T, A>) -> Ordering
Comparison for two Arc
s.
The two are compared by calling cmp()
on their inner values.
§Examples
use std::sync::Arc;
use std::cmp::Ordering;
let five = Arc::new(5);
assert_eq!(Ordering::Less, five.cmp(&Arc::new(6)));
1.21.0 · Source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
1.0.0 · Source§impl<T, A> PartialEq for Arc<T, A>
impl<T, A> PartialEq for Arc<T, A>
Source§fn eq(&self, other: &Arc<T, A>) -> bool
fn eq(&self, other: &Arc<T, A>) -> bool
Equality for two Arc
s.
Two Arc
s are equal if their inner values are equal, even if they are
stored in different allocation.
If T
also implements Eq
(implying reflexivity of equality),
two Arc
s that point to the same allocation are always equal.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
assert!(five == Arc::new(5));
Source§fn ne(&self, other: &Arc<T, A>) -> bool
fn ne(&self, other: &Arc<T, A>) -> bool
Inequality for two Arc
s.
Two Arc
s are not equal if their inner values are not equal.
If T
also implements Eq
(implying reflexivity of equality),
two Arc
s that point to the same value are always equal.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
assert!(five != Arc::new(6));
1.0.0 · Source§impl<T, A> PartialOrd for Arc<T, A>
impl<T, A> PartialOrd for Arc<T, A>
Source§fn partial_cmp(&self, other: &Arc<T, A>) -> Option<Ordering>
fn partial_cmp(&self, other: &Arc<T, A>) -> Option<Ordering>
Partial comparison for two Arc
s.
The two are compared by calling partial_cmp()
on their inner values.
§Examples
use std::sync::Arc;
use std::cmp::Ordering;
let five = Arc::new(5);
assert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6)));
Source§fn lt(&self, other: &Arc<T, A>) -> bool
fn lt(&self, other: &Arc<T, A>) -> bool
Less-than comparison for two Arc
s.
The two are compared by calling <
on their inner values.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
assert!(five < Arc::new(6));
Source§fn le(&self, other: &Arc<T, A>) -> bool
fn le(&self, other: &Arc<T, A>) -> bool
‘Less than or equal to’ comparison for two Arc
s.
The two are compared by calling <=
on their inner values.
§Examples
use std::sync::Arc;
let five = Arc::new(5);
assert!(five <= Arc::new(5));
1.73.0 · Source§impl Read for Arc<File>
impl Read for Arc<File>
Source§fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
Source§fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
read
, except that it reads into a slice of buffers. Read moreSource§fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)Source§fn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)Source§fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
buf
. Read moreSource§fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · Source§fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moreSource§fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · Source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Read
. Read more1.73.0 · Source§impl Seek for Arc<File>
impl Seek for Arc<File>
Source§fn seek(&mut self, pos: SeekFrom) -> Result<u64, Error>
fn seek(&mut self, pos: SeekFrom) -> Result<u64, Error>
Source§fn stream_len(&mut self) -> Result<u64, Error>
fn stream_len(&mut self) -> Result<u64, Error>
seek_stream_len
)Source§fn stream_position(&mut self) -> Result<u64, Error>
fn stream_position(&mut self) -> Result<u64, Error>
§impl<S> Subscriber for Arc<S>where
S: Subscriber + ?Sized,
impl<S> Subscriber for Arc<S>where
S: Subscriber + ?Sized,
§fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
§fn max_level_hint(&self) -> Option<LevelFilter>
fn max_level_hint(&self) -> Option<LevelFilter>
Subscriber
will
enable, or None
, if the subscriber does not implement level-based
filtering or chooses not to implement this method. Read more§fn record_follows_from(&self, span: &Id, follows: &Id)
fn record_follows_from(&self, span: &Id, follows: &Id)
§fn event_enabled(&self, event: &Event<'_>) -> bool
fn event_enabled(&self, event: &Event<'_>) -> bool
Event
] should be recorded. Read more§fn clone_span(&self, id: &Id) -> Id
fn clone_span(&self, id: &Id) -> Id
§fn drop_span(&self, id: Id)
fn drop_span(&self, id: Id)
Subscriber::try_close
instead§fn current_span(&self) -> Current
fn current_span(&self) -> Current
§unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()>
unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()>
self
is the same type as the provided TypeId
, returns an untyped
*const
pointer to that type. Otherwise, returns None
. Read more§fn on_register_dispatch(&self, subscriber: &Dispatch)
fn on_register_dispatch(&self, subscriber: &Dispatch)
Dispatch
]. Read more1.43.0 · Source§impl<T, A, const N: usize> TryFrom<Arc<[T], A>> for Arc<[T; N], A>where
A: Allocator,
impl<T, A, const N: usize> TryFrom<Arc<[T], A>> for Arc<[T; N], A>where
A: Allocator,
1.73.0 · Source§impl Write for Arc<File>
impl Write for Arc<File>
Source§fn write(&mut self, buf: &[u8]) -> Result<usize, Error>
fn write(&mut self, buf: &[u8]) -> Result<usize, Error>
Source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)Source§fn flush(&mut self) -> Result<(), Error>
fn flush(&mut self) -> Result<(), Error>
1.0.0 · Source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)§impl<'a, T> Writeable for Arc<T>where
T: Writeable + ?Sized,
impl<'a, T> Writeable for Arc<T>where
T: Writeable + ?Sized,
§fn write_to<W>(&self, sink: &mut W) -> Result<(), Error>
fn write_to<W>(&self, sink: &mut W) -> Result<(), Error>
write_to_parts
, and discards any
Part
annotations.§fn write_to_parts<W>(&self, sink: &mut W) -> Result<(), Error>where
W: PartsWrite + ?Sized,
fn write_to_parts<W>(&self, sink: &mut W) -> Result<(), Error>where
W: PartsWrite + ?Sized,
Part
annotations to the given sink. Errors from the
sink are bubbled up. The default implementation delegates to write_to
,
and doesn’t produce any Part
annotations.§fn writeable_length_hint(&self) -> LengthHint
fn writeable_length_hint(&self) -> LengthHint
§fn write_to_string(&self) -> Cow<'_, str>
fn write_to_string(&self) -> Cow<'_, str>
String
with the data from this Writeable
. Like ToString
,
but smaller and faster. Read moreimpl<T> CartablePointerLike for Arc<T>
impl<T> CloneStableDeref for Arc<T>where
T: ?Sized,
impl<T> CloneableCart for Arc<T>where
T: ?Sized,
impl<T> CloneableCartablePointerLike for Arc<T>
impl<T, U, A> CoerceUnsized<Arc<U, A>> for Arc<T, A>
impl<T, A> DerefPure for Arc<T, A>
impl<T, U> DispatchFromDyn<Arc<U>> for Arc<T>
impl<T, A> Eq for Arc<T, A>
impl<T, A> PinCoerceUnsized for Arc<T, A>
impl<T, A> Send for Arc<T, A>
impl<T> StableDeref for Arc<T>where
T: ?Sized,
impl<T, A> Sync for Arc<T, A>
impl<T, A> Unpin for Arc<T, A>
impl<T, A> UnwindSafe for Arc<T, A>
impl<T, A> UseCloned for Arc<T, A>
Auto Trait Implementations§
Blanket Implementations§
§impl<T> AsErrorSource for Twhere
T: Error + 'static,
impl<T> AsErrorSource for Twhere
T: Error + 'static,
§fn as_error_source(&self) -> &(dyn Error + 'static)
fn as_error_source(&self) -> &(dyn Error + 'static)
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
§impl<T> Datum for Twhere
T: Array,
impl<T> Datum for Twhere
T: Array,
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.§impl<R> FixedIntReader for Rwhere
R: Read,
impl<R> FixedIntReader for Rwhere
R: Read,
§fn read_fixedint<FI>(&mut self) -> Result<FI, Error>where
FI: FixedInt,
fn read_fixedint<FI>(&mut self) -> Result<FI, Error>where
FI: FixedInt,
FI
. Read more§impl<W> FixedIntWriter for Wwhere
W: Write,
impl<W> FixedIntWriter for Wwhere
W: Write,
fn write_fixedint<FI>(&mut self, n: FI) -> Result<usize, Error>where
FI: FixedInt,
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more§impl<T> Pointable for T
impl<T> Pointable for T
§impl<R> ReadBytesExt for R
impl<R> ReadBytesExt for R
§fn read_u8(&mut self) -> Result<u8, Error>
fn read_u8(&mut self) -> Result<u8, Error>
§fn read_i8(&mut self) -> Result<i8, Error>
fn read_i8(&mut self) -> Result<i8, Error>
§fn read_u16<T>(&mut self) -> Result<u16, Error>where
T: ByteOrder,
fn read_u16<T>(&mut self) -> Result<u16, Error>where
T: ByteOrder,
§fn read_i16<T>(&mut self) -> Result<i16, Error>where
T: ByteOrder,
fn read_i16<T>(&mut self) -> Result<i16, Error>where
T: ByteOrder,
§fn read_u24<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
fn read_u24<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
§fn read_i24<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
fn read_i24<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
§fn read_u32<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
fn read_u32<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
§fn read_i32<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
fn read_i32<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
§fn read_u48<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
fn read_u48<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
§fn read_i48<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
fn read_i48<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
§fn read_u64<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
fn read_u64<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
§fn read_i64<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
fn read_i64<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
§fn read_u128<T>(&mut self) -> Result<u128, Error>where
T: ByteOrder,
fn read_u128<T>(&mut self) -> Result<u128, Error>where
T: ByteOrder,
§fn read_i128<T>(&mut self) -> Result<i128, Error>where
T: ByteOrder,
fn read_i128<T>(&mut self) -> Result<i128, Error>where
T: ByteOrder,
§fn read_uint<T>(&mut self, nbytes: usize) -> Result<u64, Error>where
T: ByteOrder,
fn read_uint<T>(&mut self, nbytes: usize) -> Result<u64, Error>where
T: ByteOrder,
§fn read_int<T>(&mut self, nbytes: usize) -> Result<i64, Error>where
T: ByteOrder,
fn read_int<T>(&mut self, nbytes: usize) -> Result<i64, Error>where
T: ByteOrder,
§fn read_uint128<T>(&mut self, nbytes: usize) -> Result<u128, Error>where
T: ByteOrder,
fn read_uint128<T>(&mut self, nbytes: usize) -> Result<u128, Error>where
T: ByteOrder,
§fn read_int128<T>(&mut self, nbytes: usize) -> Result<i128, Error>where
T: ByteOrder,
fn read_int128<T>(&mut self, nbytes: usize) -> Result<i128, Error>where
T: ByteOrder,
§fn read_f32<T>(&mut self) -> Result<f32, Error>where
T: ByteOrder,
fn read_f32<T>(&mut self) -> Result<f32, Error>where
T: ByteOrder,
§fn read_f64<T>(&mut self) -> Result<f64, Error>where
T: ByteOrder,
fn read_f64<T>(&mut self) -> Result<f64, Error>where
T: ByteOrder,
§fn read_u16_into<T>(&mut self, dst: &mut [u16]) -> Result<(), Error>where
T: ByteOrder,
fn read_u16_into<T>(&mut self, dst: &mut [u16]) -> Result<(), Error>where
T: ByteOrder,
§fn read_u32_into<T>(&mut self, dst: &mut [u32]) -> Result<(), Error>where
T: ByteOrder,
fn read_u32_into<T>(&mut self, dst: &mut [u32]) -> Result<(), Error>where
T: ByteOrder,
§fn read_u64_into<T>(&mut self, dst: &mut [u64]) -> Result<(), Error>where
T: ByteOrder,
fn read_u64_into<T>(&mut self, dst: &mut [u64]) -> Result<(), Error>where
T: ByteOrder,
§fn read_u128_into<T>(&mut self, dst: &mut [u128]) -> Result<(), Error>where
T: ByteOrder,
fn read_u128_into<T>(&mut self, dst: &mut [u128]) -> Result<(), Error>where
T: ByteOrder,
§fn read_i8_into(&mut self, dst: &mut [i8]) -> Result<(), Error>
fn read_i8_into(&mut self, dst: &mut [i8]) -> Result<(), Error>
§fn read_i16_into<T>(&mut self, dst: &mut [i16]) -> Result<(), Error>where
T: ByteOrder,
fn read_i16_into<T>(&mut self, dst: &mut [i16]) -> Result<(), Error>where
T: ByteOrder,
§fn read_i32_into<T>(&mut self, dst: &mut [i32]) -> Result<(), Error>where
T: ByteOrder,
fn read_i32_into<T>(&mut self, dst: &mut [i32]) -> Result<(), Error>where
T: ByteOrder,
§fn read_i64_into<T>(&mut self, dst: &mut [i64]) -> Result<(), Error>where
T: ByteOrder,
fn read_i64_into<T>(&mut self, dst: &mut [i64]) -> Result<(), Error>where
T: ByteOrder,
§fn read_i128_into<T>(&mut self, dst: &mut [i128]) -> Result<(), Error>where
T: ByteOrder,
fn read_i128_into<T>(&mut self, dst: &mut [i128]) -> Result<(), Error>where
T: ByteOrder,
§fn read_f32_into<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
fn read_f32_into<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
§fn read_f32_into_unchecked<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
fn read_f32_into_unchecked<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
read_f32_into
instead§impl<SS, SP> SupersetOf<SS> for SPwhere
SS: SubsetOf<SP>,
impl<SS, SP> SupersetOf<SS> for SPwhere
SS: SubsetOf<SP>,
§fn to_subset(&self) -> Option<SS>
fn to_subset(&self) -> Option<SS>
self
from the equivalent element of its
superset. Read more§fn is_in_subset(&self) -> bool
fn is_in_subset(&self) -> bool
self
is actually part of its subset T
(and can be converted to it).§fn to_subset_unchecked(&self) -> SS
fn to_subset_unchecked(&self) -> SS
self.to_subset
but without any property checks. Always succeeds.§fn from_subset(element: &SS) -> SP
fn from_subset(element: &SS) -> SP
self
to the equivalent element of its superset.Source§impl<T> ToHex for T
impl<T> ToHex for T
Source§fn encode_hex<U>(&self) -> Uwhere
U: FromIterator<char>,
fn encode_hex<U>(&self) -> Uwhere
U: FromIterator<char>,
self
into the result. Lower case
letters are used (e.g. f9b4ca
)Source§fn encode_hex_upper<U>(&self) -> Uwhere
U: FromIterator<char>,
fn encode_hex_upper<U>(&self) -> Uwhere
U: FromIterator<char>,
self
into the result. Upper case
letters are used (e.g. F9B4CA
)