=============================
PyPy's ctypes implementation 
=============================

.. Summary
.. ========


サマリー
========


.. Terminology:

.. * application level code - code written in full Python

.. * interpreter level code - code written in RPython, compiled
..   to something else, say C, part of the interpreter.

専門用語の定義:


* アプリケーションレベルコード - すべて Python で書かれたコード
* インタプリタレベルコード - RPython で書かれ、インタプリタを C 等に変換したもの

.. PyPy's ctypes implementation in its current state proves the
.. feasibility of implementing a module with the same interface and
.. behavior for PyPy as ctypes for CPython.

現状、PyPy における ctypes によるモジュールの実装は CPython における ctypes と同様のインターフェスとふるまいを保証しています。

.. PyPy's implementation internally uses `libffi`_ like CPython's ctypes.
.. In our implementation as much as possible of the code is written in
.. full Python, not RPython. In CPython's situation, the equivalent would
.. be to write as little as possible code in C.  We essentially favored
.. rapid experimentation over worrying about speed for this first trial
.. implementation. This allowed to provide a working implementation with
.. a large part of ctypes features in 2 months real time.

PyPy の実装では、 CPython における ctypes の `libffi`_ のようなものを内部的に利用します。
実装は RPython ではなく、すべて Python で書かれています。
CPython では、同様のものが C で書かれています。
私たちは基本的に実装の早さよりも、動作の速さを重視しています。
実際 ctypes のほとんどの機能の実装に 2 ヶ月間をかけています。

.. We reused the ``ctypes`` package version 1.0.2 as-is from CPython. We
.. implemented ``_ctypes`` which is a C module in CPython mostly in pure
.. Python based on a lower-level layer extension module ``_rawffi``.

CPython 同様に ``ctypes`` のバージョン 1.0.2 を再利用しています。
CPython の C モジュールではなく、
ピュア Python ベースの低レベルのレイヤの拡張モジュール ``_rawffi`` で ``_ctypes`` を実装しています。

.. _`libffi`: http://sources.redhat.com/libffi/

.. Low-level part: ``_rawffi``
.. ============================

低レベル部品: ``_rawffi``
=========================

.. This PyPy extension module (``pypy/module/_rawffi``) exposes a simple interface
.. to create C objects (arrays and structures) and calling functions
.. in dynamic libraries through libffi. Freeing objects in most cases and making
.. sure that objects referring to each other are kept alive is responsibility of the higher levels.

この PyPy 拡張モジュール (``pypy/module/_rawffi``) は C オブジェクト (配列や構造体) の作成や、
libffi 経由で動的ライブラリの関数を呼び出すためのシンプルなインターフェースを提供します。
大抵のオブジェクトの開放の場合、
互いを参照しているオブジェクトの生存確認はより高レベルで解決します。

.. This module uses bindings to libffi which are defined in ``pypy/rlib/libffi.py``.

このモジュールは ``pypy/rlib/libffi.py`` に定義されている libffi バインディングを利用します。

.. We tried to keep this module as small as possible. It is conceivable
.. that other implementations (e.g. Jython) could use our ctypes
.. implementation by writing their version of ``_rawffi``.

このモジュールはできるだけコンパクトなままにしておくつもりです。
他の実装の場合 (例えば Jython) でも、それぞれのバージョンの ``_rawffi`` を書くことにより、
ctypes 実装を利用できると考えています。

.. High-level parts
.. =================

高レベル部品
============

.. The reused ``ctypes`` package lives in ``lib_pypy/ctypes``. ``_ctypes``
.. implementing the same interface as ``_ctypes`` in CPython is in
.. ``lib_pypy/_ctypes``.

再利用している ``ctypes`` は ``lib_pypy/ctypes`` にあります。
CPython の ``_ctypes`` 同じインターフェースの実装の ``_ctypes`` は ``lib_pypy/_ctypes`` にあります。

.. Discussion and limitations
.. =============================

考察と制限
==========

.. Reimplementing ctypes features was in general possible. PyPy supports
.. pluggable garbage collectors, some of them are moving collectors, this
.. means that the strategy of passing direct references inside Python
.. objects to an external library is not feasible (unless the GCs
.. support pinning, which is not the case right now).  The consequence of
.. this is that sometimes copying instead of sharing is required, this
.. may result in some semantics differences. C objects created with
.. _rawffi itself are allocated outside of the GC heap, such that they can be
.. passed to external functions without worries.

ctypes の機能のほとんどは再実装可能でした。
PyPy は拡張可能なガーベージコレクタをサポートしており、
そのいくつかのコレクタは動いており、
これは Python オブジェクトの内部で直接参照している外部のライブラリの状態の解析ができないことを意味しています
(GC のサポートを限定していない場合は、このケースは当てはまりません)。
その結果、いくつかのケースではいくつかの動作の違いがあるため、共有せずに複製する必要がでてきます。
_rawffi によて作成された C オブジェクトは GC のヒープ外に割り当てられ、
とくになにも気にすることなく外部関数に引き継ぐことができます。

.. Porting the implementation to interpreter-level should likely improve
.. its speed.  Furthermore the current layering and the current _rawffi
.. interface require more object allocations and copying than strictly
.. necessary; this too could be improved.

実装のインタプリタレベルのポーティングによりその速度は改善されます。
また、現状のレイヤリングと現状の _rawffi インターフェースは、
さらに厳格なオブジェクトの配置と複製を必要とします;
これは改善することができました。

.. Here is a list of the limitations and missing features of the
.. current implementation:

現状の実装における制限と実装されてない機能は以下のようなものがあります。

.. * No support for ``PyXxx`` functions from ``libpython``, for obvious reasons.

.. * We copy Python strings instead of having pointers to raw buffers

.. * Features we did not get to implement:

..   - custom alignment and bit-fields

..   - resizing (``resize()`` function)

..   - non-native byte-order objects

..   - callbacks accepting by-value structures

..   - slight semantic differences that ctypes makes
..     between its primitive types and user subclasses
..     of its primitive types

* ``libpython`` の ``PyXxx`` 関数は明確な理由からサポートされていません。

* 生バッファへのポインタの保持ではなく Python の文字列を複製しています

* 実装していない機能

  - カスタムアラインメントとビットフィールド

  - リサイズ (``resize()`` 関数)

  - 非ネィティブバイトオーダオブジェクト

  - By-value オブジェクトへのコールバックの許可

  - ctypes のプリミティブ型とユーザサブクラスのプリミティブ型にはいくつかの動作の違いがあります

.. Running application examples
.. ==============================

アプリケーションの実装例
========================

.. `pyglet`_ is known to run. We also had some success with pygame-ctypes (which is no longer maintained) and with a snapshot of the experimental pysqlite-ctypes. We will only describe how to run the pyglet examples.

`pyglet`_ の実装が知られています。
pygame-ctypes (しばらくメンテナンスされていません) や pysqlite-ctypes のスナップショット等の成功例があります。
pyglet の実装方法を例示します。

pyglet
------

.. We tried pyglet checking it out from its repository at revision 1984.

pyglet のリポジトリからリビジョン 1984 をチェックアウトします。

.. From pyglet, the following examples are known to work:

pyglet では以下の動作例が知られています:

  - opengl.py
  - multiple_windows.py
  - events.py
  - html_label.py
  - timer.py
  - window_platform_event.py
  - fixed_resolution.py

.. The pypy-c translated to run the ctypes tests can be used to run the pyglet examples as well. They can be run like e.g.::

ctypes のテストを実行する pypy-c は、同様に pyglet の例の実行に用いることができます。

    $ cd pyglet/
    $ PYTHONPATH=. ../ctypes-stable/pypy/translator/goal/pypy-c examples/opengl.py

.. they usually should be terminated with ctrl-c. Refer to the their doc strings for details about how they should behave.

通常 ctrl-c で終了することができます。

.. The following examples don't work for reasons independent from ctypes:

..   - image_convert.py needs PIL
..   - image_display.py needs PIL
..   - astraea/astraea.py needs PIL

以下の例は ctypes から独立しているため動作しません。

  - image_convert.py needs PIL
  - image_display.py needs PIL
  - astraea/astraea.py needs PIL

.. We did not try the following examples:

..   - media_player.py needs avbin or at least a proper sound card setup for
..     .wav files
..   - video.py needs avbin
..   - soundscape needs avbin

以下の例は試していません:

  - media_player.py は avbin または、少なくとも .wav ファイルを再生するために適切なサウンドカードのセットアップが必要です
  - video.py は avbin が必要です
  - soundscape は avbin が必要です

.. _`pyglet`: http://pyglet.org/


.. ctypes configure
.. ================

ctypes のコンフィグレーション
=============================

.. We also released ``ctypes-configure``, which is an experimental package
.. trying to approach the portability issues of ctypes-based code.

ctypes ベースのコードの移植性の課題を解決するための実験的なパッケージとして ``ctypes-configure`` もリリースしています。

.. idea
.. ----

アイデア
--------

.. One of ctypes problems is that ctypes programs are usually not very
.. platform-independent. We created ctypes_configure, which invokes c
.. compiler (via distutils) for various platform-dependent details like
.. exact sizes of types (for example size_t), ``#defines``, exact outline of
.. structures etc. It replaces in this regard code generator (h2py).

ctypes の問題点のひとつは、通常 ctypes プログラムにプラットフォーム依存があることです。
各プラットフォームに依存する型のサイズ (例えば size_t)、
``#defines`` や構造体のアウトライン等の細部のために C コンパイラを呼び出す (distutils 経由) 
ctypes_configure を作成し、

.. installation
.. ------------

インストール
------------

``easy_install ctypes_configure``

.. usage
.. -----

利用方法
--------

.. `ctypes_configure/doc/sample.py`_ explains in details how to use it.

`ctypes_configure/doc/sample.py`_ で詳細な利用方法について解説しています。


.. include:: _ref.txt