Rust api 디자인

Designing interfaces

• Rust API Guidelines 꼭 읽어보자!

• Rust RFC 1105 읽기를 권한다.

• The Cargo Book on SemVer compatibility

Unsurprising

The principle of least surprise

Naming practices

Common traits for types

• Debug trait 거의 모든 대부분의 타입이 구현해야 한다. #[derive(Debug)]가 가장 많이 쓰이는 방법

• Send and Sync trait 만약 타입이 Sync, Send 두가지 트레잇을 구현하지 않는다면, 반드시 합당한 이유가 있어야하며, 이것은 문서화 되어 있어야 한다. Send가 없다면 Mutex와 사용할 수 없고, Sync가 없다면 Arc나 static 타입으로 사용할 수 없다. thread pool에서 동작하는 async world에서 두 트레잇을 구현하지 않는다면 당신에게 큰 좌절감을 안겨줄 수 있다.

• Clone and Default trait nearly universal trait 구현하기 쉽고, 없다면 사용자가 놀랄만한 trait 구현하지 않는다면 반드시 문서화한다.

• Comparison traits (PartialEq, PartialOrd, Hash, Eq and Ord)
• PartialEq 사용자가 갈망하는 trait, 타입을 비교(== or assert_eq!)할 때 필요하다.
• PartialOrd and Hash 특수한 경우에 사용된다. ex) 타입이 hashmap과 같은 컬렉션의 key로 사용
• Serialize and Deserialize serde는 외부 라이브러리 이지만 대부분의 라이브러리들이 serde를 구현하고 있으니 걱정말고 쓰자

• Copy trait Copy는 보편적으로 구현되어 있을 것이라고 기대하는 trait이 아니다. 사용자는 보통 사본을 만들 때 clone을 호출한다.

Ergonomic Trait Implementations

• blanket implementation:

impl<T> ToString for T where
T: Display + ?Sized,
{ ... }

Wrapper Types

Flexible

fn frobnicate1(s: String) -> String
fn frobnicate2(s: &str) -> Cow<'_, str>
fn frobnicate3(s: impl AsRef<str>) -> impl AsRef<str>

Generic Arguments

Object Safety

Borrowed vs. Owned

Fallible and Blocking Destructors

• type이 Drop을 구현하는 경우, type의 어떤 필드도 destructor에서 move out 할 수 없다

• drop은 '&mut self'를 인자로 갖기 때문에 drop의 구현은 explicit destructor를 직접 호출할 수 없다.

• Option을 사용하여 NewType wrapper으로 type을 감싼다. Option::take를 양쪽 destructor에서 모두 사용 가능, inner type이 존재하는 경우에만 explicit destructor를 호출가능, inner type은 drop을 구현하지 않기 때문에 모든 필드의 소유권을 가져올 수 있음 하지만 top-level의 모든 메서드는 Inner type에 접근하기 위해서 Option을 거쳐서 사용해야 하는 불편함이 있다. 이 방법의 단점은 모든 필드를 Option으로 사용하여 코드가 장황해질 수 있다.

• 두번째 방법은 각 필드를 takeable하게 만드는 것이다. Option을 take하여 None으로 만드는 것 처럼, 다른 타입도 마찬가지 방법을 사용할 수 있다. Vec나 HashMap은 std::mem::take를 사용하여 교체할 수 있다. (타입이 empty 값을 지원하는 경우)

• 세번째 방법은 데이터를 ManuallyDrop 타입으로 감싸는 것이다. ManuallyDrop은 inner type을 dereference하여 unwrap이 불필요하고, ManuallyDrop::take를 drop내에서 사용하여 소유권을 destruction time에 가져올 수 있다. 단점은 ManaullyDrop::take가 unsafe라는 것. 이미 take를 수행한 값을 다시 take했을 때 에러를 탐지해줄 수 있는 안전장치가 없다. take를 여러번 수행하는 것은 undefined behaviour로 주의가 필요하다.

Obvious

Documentation

• 예측할 수 없는 예외적인 사항을 문서화하라 Panic이 대표적인 예, 패닉이 발생할 수 있는 상황을 문서화하라 Error도 마찬가지. unsafe 함수라면 어떤 조건에서 safe한지 기술하라

• crate와 module level에서 end-to-end usage examples 를 제공하라 어떤 type이나 메서드의 예를 제공하는 것보다, module 또는 crate가 제공하는 타입/메서드들이 어떻게 함께 맞물려 돌아가는지를 사용자가 알 수 있게 하는 것이 중요하다.

• Documentation을 조직하라 모든 type, trait, function들을 하나의 top-level 모듈에 위치시키면 사용자가 어디서부터 파악해야할지 알기 어렵다. 관련있는 항목들끼리 모듈 그룹으로 묶고, 관려 있는 각 아이템은 링크를 추가하자
• interface 중에서 public으로 사용하길 의도하지 않았지만, legacy와 호환을 위해 남겨둔 public interface는 #[doc(hidden)]으로 문서에 노출하지 않을 수 있다.

• 가능하다면 양질의 Documentation을 제공하라 concepts, data structures, algorithms 또는 다른 측면 등을 설명하기 위해 외부 리소스(RFCs, blog posts, and white papers)의 링크를 추가 configuration을 위해 #[doc(cfg(...))], 검색을 쉽게하기 위해 #[doc(alias = "...")]

Type System Guidance

• Semantic typing: Type 이름이 값에 의미를 부여

• Zero sized type technique

struct Grounded;
struct Launched;

struct Rocket<Stage = Grounded> {
    stage: std::marker::PhantomData<Stage>,
}

impl Default for Rocket<Grounded> {}
impl Rocket<Grounded> {
    pub fn launch(self) -> Rocket<Launched> {}
}
impl Rocket<Launched> {
    pub fn accelerate(&mut self) {}
    pub fn decelerate(&mut self) {}
}

impl<Stage> Rocket<Stage> {
    pub fn color(&self) -> Color {}
    pub fn weight(&self) --> Kilograms {}
}

fn main() {
  let rocket = Rocket::default(); // Rocket<Grounded>
  rocket.accelerate(); // error!
  let rocket = rocket.launch(); // Rocket<Launched>
  rocket.accelerate();
}

각 stage를 나타내기 위해 unit type Grounded, Launched를 정의 stage는 메타정보만 제공하고 컴파일타임에 제거하기 위해 PhantomData를 사용 Rocket은 Grounded stage로 생성 -> launch -> accelerate/decelerate color(), weight()는 모든 stage에서 사용 가능
사용자가 메서드를 잘못된 stage에서 호출할 가능성을 차단해버렸다.
이 개념은 다양하게 확장가능 예) pointer와 bool 두개의 인자를 받는 함수가 bool 값이 true인 경우에만 pointer를 처리하는 경우 -> enum을 사용하여 두개의 인자를 하나로 만든다.

• #[must_use] annotation: 작지만 강력한 기능 type, trait, funtions에 사용할 수 있으며, 사용자가 이를 처리하지 않으면 컴파일러 워닝을 발생 예) Result 남용하지 않도록 주의, 사용자가 실수하기 쉬운 곳에 사용할 것

Constrained

Type Modifications

// in your interface
pub struct Uint;
// in user code
let u = lib::Uint

// in your interface
pub struct Uint { pub field: bool };

// in user code
fn is_true(u: lib::Uint) -> bool {
    matches!(u, Uint { field: true })
}

exhaustive: (하나도 빠뜨리는 것 없이) 철저한[완전한]

#[non_exhaustive]
pub struct Config {
    pub window_width: u16,
    pub window_height: u16,
}

#[non_exhaustive]
pub enum Error {
    Message(String),
    Other,
}

pub enum Message {
    #[non_exhaustive] Send { from: u32, to: u32, contents: String },
    #[non_exhaustive] Reaction(u32),
    #[non_exhaustive] Quit,
}

// Non-exhaustive structs can be constructed as normal within the defining crate.
let config = Config { window_width: 640, window_height: 480 };

// Non-exhaustive structs can be matched on exhaustively within the defining crate.
if let Config { window_width, window_height } = config {
    // ...
}

let error = Error::Other;
let message = Message::Reaction(3);

// Non-exhaustive enums can be matched on exhaustively within the defining crate.
match error {
    Error::Message(ref s) => { },
    Error::Other => { },
}

match message {
    // Non-exhaustive variants can be matched on exhaustively within the defining crate.
    Message::Send { from, to, contents } => { },
    Message::Reaction(id) => { },
    Message::Quit => { },
}

// `Config`, `Error`, and `Message` are types defined in an upstream crate that have been
// annotated as `#[non_exhaustive]`.
use upstream::{Config, Error, Message};

// Cannot construct an instance of `Config`, if new fields were added in
// a new version of `upstream` then this would fail to compile, so it is
// disallowed.
let config = Config { window_width: 640, window_height: 480 };

// Can construct an instance of `Error`, new variants being introduced would
// not result in this failing to compile.
let error = Error::Message("foo".to_string());

// Cannot construct an instance of `Message::Send` or `Message::Reaction`,
// if new fields were added in a new version of `upstream` then this would
// fail to compile, so it is disallowed.
let message = Message::Send { from: 0, to: 1, contents: "foo".to_string(), };
let message = Message::Reaction(0);

// Cannot construct an instance of `Message::Quit`, if this were converted to
// a tuple-variant `upstream` then this would fail to compile.
let message = Message::Quit;

// `Config`, `Error`, and `Message` are types defined in an upstream crate that have been
// annotated as `#[non_exhaustive]`.
use upstream::{Config, Error, Message};

// Cannot match on a non-exhaustive enum without including a wildcard arm.
match error {
  Error::Message(ref s) => { },
  Error::Other => { },
  _ => {},
  // would compile with: `_ => {},`
}

// Cannot match on a non-exhaustive struct without a wildcard.
if let Ok(Config { window_width, window_height }) = config {
    // would compile with: `..`
}

match message {
  // Cannot match on a non-exhaustive struct enum variant without including a wildcard.
  Message::Send { from, to, contents } => { },
  // Cannot match on a non-exhaustive tuple or unit enum variant.
  Message::Reaction(type) => { },
  Message::Quit => { },
}

• reference: https://doc.rust-lang.org/reference/attributes/type_system.html

Trait Implementation

In chapter 3, Rust's coherence rules disallow multiple implementations of a given trait for a given type

• (generally) trait의 blanket 구현을 추가 (downstream code에서 구현이 추가되었을 수 있다.)

• (must) existing type 에 foreign trait의 구현 추가

• (must) foreign type 에 existing trait의 구현 추가
• 위 두가지 케이스에서 breaking change인 이유는 foreign trait/type 의 구현이 충돌할 수 있기 때문이다.

• trait 구현을 삭제
• 새로운 타입에 대한 trait 구현을 추가하는 것은 문제가 되지 않는다. 구현이 충돌할 가능성이 없기 때문이다.

• existing type 에 어떤 trait의 구현을 추가할때는 주의가 필요하다.

// crate1 1.0
pub struct Unit;
pub trait Foo1 { fn foo(&self) }
// note that Foo1 is not implemented for Unit

// crate2; depends on crate1 1.0
use crate1::{Unit, Foo1};

trait Foo2 { fn foo(&self) }
impl Foo2 for Unit { .. }
fn main() {
    Unit.foo();
}

Unit struct에 Foo1 trait의 구현을 추가하면 main()에서는 foo() 호출이 Foo1, Foo2 중 어느 trait의 구현을 가리키는지 알 수 없게된다.(breaking change) 이 조건은 기존 트레잇의 구현을 추가하는 것 뿐만 아니라 새로운 트레잇을 추가하는 경우에도 마찬가지로 적용된다. prelude module로 사용자가 wildcard import(*)를 사용하도록 interface를 제공하는 경우 특히 주의하자.

• (most) existing trait을 변경
• method signature를 변경
• 새로운 method 추가(default 구현을 가진 method를 추가하는 것은 문제가 되지 않는다)

pub trait CanUseCannotImplement: sealed::Sealed { ..  }
mod sealed {
    pub trait Sealed {}
    impl<T> Sealed for T where T: TraitBounds {} // explicitly allow
}
impl<T> CanUseCannotImplement for T where T: TraitBounds {}

Hidden Contracts