このセクションでは、グローバルに共有されるシングルトンの実装方法を説明します。 The embedded Rust bookは、Rust特有のローカルで所有されるシングルトンを説明しました。 グローバルシングルトンは、本質的にCやC++で見かけるシングルトンパターンです。 これは、組込み開発固有のものではありませんが、シンボルに関係するため、embedonomiconに相応しい内容のように思えます。
TODO(resources team) link "the embedded Rust book" to the singletons section when it's up
グローバルシングルトンを説明するために、このセクションでは、前のセクションで開発したロガーを、
グローバルにログ出力できるように拡張します。
結果は、the embedded Rust bookで説明した#[global_allocator]
フィーチャと非常に似たものになります。
TODO(resources team) link
#[global_allocator]
to the collections chapter of the book when it's in a more stable location.
やりたいことを、下記にまとめます。
前のセクションでは、Log
トレイトを実装している特定のロガーを通してログメッセージを出力するために、log!
マクロを作りました。
log!
マクロのシンタックスは、log!(logger, "String")
です。
このマクロを、log!("String")
でも動くように拡張します。
logger
なしのバージョンを使うと、グローバルロガーを通してメッセージをログ出力しなければなりません。
これは、std::println!
が動作する方法と同じです。
また、何がグローバルロガーか、を宣言するための機構が必要です。
これは、#[global_allocator]
と似ている部分です。
グローバルロガーが最上位クレートで宣言される可能性があり、 グローバルロガーの型もまた最上位クレートで定義される可能性があります。 この場合、依存関係から正確なグローバルロガーの型を知ることはできません。 この場合をサポートするために、いくらか間接的な方法が必要になります。
log
クレートにグローバルロガーの型をハードコーディングする代わりに、logクレート内で、
グローバルロガーのインタフェースだけを宣言します。
そのインタフェースは、log
クレートに新しく追加するGlobalLog
というトレイトです。
log!
マクロもそのトレイトを使うようにします。
$ cat ../log/src/lib.rs
{{#include ../ci/singleton/log/src/lib.rs}}
解説することがたくさんあります。
トレイトから始めましょう。
{{#include ../ci/singleton/log/src/lib.rs:4:6}}
GlobalLog
とLog
とは、log
メソッドを持っています。違いは、GlobalLog.log
がレシーバの共有参照(&self
)を取ることです。
グローバルロガーはstatic
変数なので、これが必要です。後ほど、詳しく見ます。
もう1つの違う点は、GlobalLog.log
はResult
を返さないことです。
これは、呼び出し側にエラーを報告できないことを意味します。
これはグローバルシングルトンを実装するトレイトを使うための必要条件ではありません。
グローバルシングルトンでエラー処理をすることは良いことですが、グローバルバージョンのlog!
マクロの全てのユーザーが、
エラー型に同意する必要があります。
ここでは、GlobalLog
実装者がエラーを処理するようにして、インタフェースを少し簡略化します。
さらに別の違いは、GlobalLog
が実装者に、スレッド間で共有できるようにするためのSync
を要求する点です。
これは、static
変数内の値への要求です。それらの値の型は、Sync
を実装しなければなりません。
現時点では、インタフェースがこのようになっていなければならない理由は、完全には明らかではないかもしれません。 クレートの他の部分を見ることで、より明らかになっていきますので、読み進めて下さい。
次はlog!
マクロです。
{{#include ../ci/singleton/log/src/lib.rs:17:29}}
特定の$logger
なしでマクロを呼び出すと、マクロはメッセージをログ出力するためにLOGGER
と呼ばれるextern
static
変数を使います。
この変数はどこかで定義されたグローバルロガーです。そのため、extern
ブロックを使っています。
このパターンはメインインタフェースの章で見ました。
LOGGER
の型を宣言する必要があります。そうでなければ、コードは型チェックを行いません。
LOGGER
の具体的な型はここではわかりませんが、
その型がGlobalLog
トレイトを実装していることを知っています(むしろ必要としています)。
そこで、トレイトオブジェクトを使うことができます。
残りのマクロ拡張は、log!
マクロのローカルバージョンの拡張ととてもよく似ています。
そのため、前の章で説明したことは、ここでは説明しません。
ここで、LOGGER
がトレイトオブジェクトでなければならないことを知っているので、
GlobalLog
で関連型のError
を除去する理由はより明白です。もし除去しなければ、
LOGGER
の型シグネチャの中でError
の型を1つ選ばなければなりません。
これが先程、「log!
マクロの全てのユーザーが、エラー型に同意する必要があります。」と書いた意味です。
そして、最後のピースのglobal_logger!
マクロです。
これは、手続きマクロアトリビュートにもできますが、macro_rules!
でマクロを書くほうが簡単です。
{{#include ../ci/singleton/log/src/lib.rs:41:47}}
このマクロは、log!
が使用するLOGGER
変数を作ります。安定したABIインタフェースが必要なので、
no_mangle
アトリビュートを使用します。
この方法により、LOGGER
のシンボル名はlog!
マクロが期待する「LOGGER」になります。
他の重要な点は、このstatic変数の型は、log!
マクロの展開で使用される型と正確に一致しなければなりません。
もし一致しない場合、ABIの不一致により、良くないことが起こるでしょう。
新しいグローバルロガーの機能を使う例を書いてみましょう。
$ cat src/main.rs
{{#include ../ci/singleton/app/src/main.rs}}
TODO(resources team) use
cortex_m::Mutex
instead of astatic mut
variable whenconst fn
is stabilized.
依存関係にcortex-m
を追加する必要があります。
$ tail -n5 Cargo.toml
{{#include ../ci/singleton/app/Cargo.toml:11:15}}
これは、前のセクションで書いた例を移植したものです。 出力は、以前のものと同じです。
$ cargo run | xxd -p
{{#include ../ci/singleton/app/dev.out}}
$ cargo objdump --bin app -- -t | grep '\.log'
{{#include ../ci/singleton/app/dev.objdump}}
このグローバルシングルトンの実装がゼロコストでないことが気になる読者も居るかと思います。 なぜなら、トレイトオブジェクトを使用しており、vtableを参照してメソッド呼び出しを行う動的ディスパッチになるためです。
しかし、LLVMは十分に賢く、この動的ディスパッチをコンパイラの最適化 / LTOで消去してくれます。
このことは、シンボルテーブル内のLOGGER
を探すことで確認できます。
$ cargo objdump --bin app --release -- -t | grep LOGGER
{{#include ../ci/singleton/app/release.objdump}}
もしstatic
が見つからない場合、vtableがないことと、
LLVMがLOGGER.log
の呼び出しをLogger.log
の呼び出しに変換できたことを意味します。