micropython -- MicroPython 内部のアクセスと制御

関数

micropython.const(expr)

コンパイルが最適化できるように、式が定数であることを宣言するために使います。この関数の使い方は次のとおりです:

from micropython import const

CONST_X = const(123)
CONST_Y = const(2 * CONST_X + 1)

このように宣言された定数でも、宣言されているモジュールの外部からグローバル変数としてアクセス可能です。一方、定数名がアンダースコアで始まっていれば不可視となり、グローバル変数として利用でくなくなり、実行中のメモリを消費しません。

この const 関数は MicroPython パーサによって直接認識されます。上記のパターンにしたがって CPython と MicroPython の両方で動作するスクリプトを書けるよう、 micropython モジュールの一部として提供しています。

micropython.opt_level([level])

level を指定した場合、この関数はスクリプトの後続のコンパイルの最適化レベルを設定して、 None を返します。指定しない場合は、現在の最適化レベルを返します。

最適化レベルは、次のコンパイル特性を制御します。

  • アサーション: レベル 0 では、アサーションステートメントが有効になり、バイトコードにコンパイルされます。レベル 1 以上ではアサーションがコンパイルされません。
  • ビルトイン __debug__ 変数: レベル 0 でこの変数が True に展開されます。レベル 1 以上では False で展開されます。
  • ソースコード行番号: レベル 0, 1, 2 では、ソースコードの行番号がバイトコードとともに格納され、例外が発生した行番号を例外として報告することができます。レベル 3 以上では行番号が格納されません。

デフォルトの最適化レベルは通常レベル 0 です。

micropython.alloc_emergency_exception_buf(size)

緊急例外バッファ用に size バイトの RAM を割り当てます(適当なサイズは約 100 バイトです)。このバッファは(たとえば、割り込みハンドラ内などで)通常の RAM の割り当てが失敗した場合に例外を作成するために使用されます。したがって、そのような状況でも有用なトレースバック情報を提供します。

この関数を使う良い方法は、メインスクリプト(たとえば boot.py や main.py)の先頭に置くことです。そのようにしておけば、それに続くすべてのコードに対して緊急例外バッファが有効になります。

micropython.mem_info([verbose])

現在使っているメモリに関する情報を表示します。 verbose を指定すると冗長モードとなり、詳しい情報を表示します。

表示する情報は実装に依存しますが、現在使っているスタックとヒープのサイズは含みます。冗長モードではヒープ全体を出力し、どのブロックが使用され、どのブロックが空いているかを示します。

micropython.qstr_info([verbose])

現在のところのインターンド文字列(内部に蓄えられている文字列)に関する情報を表示します。 verbose を指定すると冗長モードとなり、詳しい情報を表示します。

表示する情報は実装に依存しますが、現在のインターンド文字列の数とそれが使っている RAM のサイズは含みます。冗長モードでは RAM 上のインターンド文字列すべての名前を表示します。

micropython.stack_use()

現在使われているスタックのサイズを表す整数を返します。この値そのものは特に有用ではなく、異なる時点でのスタック使用量の違いを計算するために使用されるべきです。

micropython.heap_lock()
micropython.heap_unlock()
micropython.heap_locked()

ヒープをロックまたはロック解除します。ロックされているとメモリ割り当ては発生せず、ヒープを割り当てようとした場合は MemoryError が発生します。heap_locked() は、ヒープが現在ロックされていれば真値を返します。

これらの関数はネストすることができます。つまり heap_lock() は連続して複数回呼び出すことができ、ロックの深さが増します。その後、ヒープを再度使用可能にするためには heap_unlock() を同じ回数呼び出す必要があります。

heap_unlock() と heap_locked() のどちらも現在のロックの深さを返します(heap_unlock() ではロック解除後の値)。返される値は 0 以上の整数値です。0 はヒープがロックされていないことを意味します。

ヒープがロックされた状態で REPL が有効になると、強制的にロックが解除されます。

注記: heap_locked() はほとんどのポートで有効になっていません。有効にするにはビルド時に MICROPY_PY_MICROPYTHON_HEAP_LOCKED の設定が必要となります。

micropython.kbd_intr(chr)

KeyboardInterrupt 例外を発生させる文字を設定します。デフォルトで、スクリプト実行中は 3 に設定されていて、これは Ctrl-C に該当します。この関数に -1 を渡すとCtrl-C のキャプチャが無効になり、3 を渡すと元に戻ります。

この関数は、通常は REPL で使っている文字の入力ストリームを他の目的で使う場合、そのストリームで Ctrl-C がキャプチャーされるのを防ぐために使えます。

micropython.schedule(func, arg)

関数 func が「非常にすぐに」実行されるようにスケジュールします。この関数には、単一の引数として値 arg が渡されます。「非常にすぐに」とは、MicroPython ランタイムができるだけ早くに関数を実行すること、効率的にもしようとしていること、および次の条件が満たされるよう最善を尽くすことを意味します。

  • スケジュールされた関数が他のスケジュールされた機能を横取りすることはありません。
  • スケジュールされた関数は常に「オペコード間」で実行されます。つまり、すべての基本的な Python 操作(リストへの追加など)はアトミックであることが保証されています。
  • 使用するポートは、その中でスケジュールされた関数が決して実行されないであろう「クリティカル範囲」を定義するかもしれません。関数はクリティカル範囲内でスケジュールされますが、その範囲が終了するまで実行されません。クリティカル範囲の例としては、割り込み割り込みハンドラ(IRQ)があります。

この関数の用途は、プリエントしている IRQ からのコールバックをスケジュールすることです。そのような IRQ は IRQ で実行されるコードに制限を課し(例えばヒープはロックされるかもしれません)、後で呼び出すために関数をスケジュールすることはそれらの制限を取り除きます。

注記: schedule() がプリエントしている IRQ から呼び出された場合、メモリ割り当てが許可されておらず、 schedule() に渡されるコールバックがバウンドメソッドであるときに、これを直接渡すことは失敗します。これは、バウンドメソッドへの参照を作成するとメモリが割り当てられるためです。解決策は、クラスコンストラクターでメソッドへの参照を作成し、その参照を schedule() に渡すことです。これについては 「Pythonオブジェクトの作成」の 参考資料 を参照してください 。

スケジュールされた関数を保持するための有限のキューがあり、キューがいっぱいになると schedule() は RuntimeError を起こします。