Rust Programming

8241 readers

1 users here now

founded 5 years ago

MODERATORS

nutomic@lemmy.ml

Joe@lemmy.ml

AgreeableLandscape@lemmy.ml

Need some help in understanding how to read some parts of library pages (std::process) (feddit.it)

submitted 2 weeks ago* (last edited 2 weeks ago) by dontblink@feddit.it to c/rust@lemmy.ml

7 comments fedilink hide all child comments

I am trying to understand the std::process::Termination trait.

As I'm not really used to read libraries, I took this as a challenge to try understanding a bit more about how to read them as well.

I think trying to build a library would give me better understanding, but for now...

Termination is quite easy, from the trait page I can see that this trait has single method: report, which returns an ExitCode.

pub trait Termination {
    fn report(self) -> ExitCode;
}

But when I try to dig in further and i read the page related to ExitCode, it confuses me a bit.

ExitCode is a struct, therefore it behaves like a type with many fields which define the types contained in the struct.

I cannot really understand what's the point of this type.. I don't see any fields defined in the struct and this part confuses me a lot:

The standard library provides the canonical SUCCESS and FAILURE exit codes as well as From for ExitCode for constructing other arbitrary exit codes.

I even thought this meant it was an enum which had the SUCCESS, FAILURE etc as variants, but this does not seem the case.

Can you help me to understand how this specific structs work, what exactly does it do and how I should read library pages like this one?

top 7 comments

sorted by: hot top controversial new old

[–] BB_C@programming.dev 4 points 2 weeks ago (1 children)

ExitCode is a struct, therefore it behaves like a type with many fields which define the types contained in the struct.

That's a bit too off. structs in rust are product types. A struct may define zero or more fields. And fields can be named or not. if not, such structs are called tuple structs.

In the doc page, if you clicked on source, it would have taken you to the definition.

pub struct ExitCode(imp::ExitCode);

That's a public struct with one unnamed private field. The type of the private field also happens to be private/internal.

As for why, usually the purpose is providing type safety, a unified interface,... etc. Notice how for example a windows-only extension trait is implemented that allows converting raw u32 exit codes into ExitCode.

So now you have exit codes possibly sourced from u8 or u32 values depending on the platform. And you need a safe unified interface to represent them.

I hope that's an enough starting point.

[–] Ephera@lemmy.ml 2 points 2 weeks ago* (last edited 2 weeks ago) (1 children)

Here's the source of the ExitCode implementation for Unix: https://doc.rust-lang.org/src/std/sys/pal/unix/process/process_common.rs.html#622

I'm a seasoned Rust dev and this wasn't easy for me to find. The std lib can be somewhat complex, because it needs to cover all possible use-cases...

[–] BB_C@programming.dev 3 points 2 weeks ago (1 children)

this wasn’t easy for me to find

Huh! This is the internal ExitCode, and it's two jump-to-definition calls away. The first to get to the public type definition, and the second from the public type's struct field to the private type.

[–] Ephera@lemmy.ml 3 points 2 weeks ago (1 children)

If I had downloaded the source code and opened it in my editor, then it probably would've lead me there pretty easily, yeah. But you won't normally download the source code for libraries you're looking to use. Trying to navigate there via the imports and module structure is certainly a lot more difficult, because they seem to do various re-exports, in particular for the different implementations for different operating systems...

[–] BB_C@programming.dev 1 points 2 weeks ago (1 children)

Another huh from me. Or maybe I'm missing something, because this should all be obvious.

The source of the standard library is a rustup component that everyone should have installed. As for crates, you don't have to manually download any sources. Just add the crate as a dependency, and jump around definitions as much as you like. You can remove the dependency later if you decide to not use it.

[–] Ephera@lemmy.ml 2 points 2 weeks ago

Alright, yeah, I guess, I could've opened one of my Rust projects, written down use std::process::Termination; and jumped in that way. Admittedly, I didn't think of that, but it also sounded like OP wants to learn how to read the webpage documentation...

[–] syklemil@discuss.tchncs.de 1 points 1 week ago

In addition to the other comment about the exit code, you might be interested in the exitcode crate, which offers up a BSD convention for those exit codes.

They are, essentially, just numbers on unixes and don't really have as much standardization as e.g. HTTP codes afaik. Various programs may have their own local conventions as to what an exit code means.