Crate io_lifetimes

source ·
Expand description

Experimental new types and traits to replace the Raw family of types and traits.

This API has much conceptual similarity with the Raw API, but introduces explicit concepts of ownership and borrowing:

Raw APIThis experimental API
Raw*Borrowed* and Owned*
AsRaw*As*
IntoRaw*Into*
FromRaw*From*

This gives it several advantages:

  • Less unsafe in user code!

  • Easier to understand ownership.

  • It avoids the inconsistency where AsRawFd and IntoRawFd return RawFd values that users ought to be able to trust, but aren’t unsafe, so it’s possible to fail to uphold this trust in purely safe Rust.

  • It enables a number of safe and portable convenience features, such as safe typed views and from+into conversions.

Modules

  • example_ffi
    This is just a sample of what FFI using this crate can look like.
  • raw
    Portability abstractions over Raw*.
  • views
    Typed views using temporary objects.

Structs

  • BorrowedHandle
    A borrowed handle.
  • BorrowedSocket
    A borrowed socket.
  • HandleOrInvalid
    FFI type for handles in return values or out parameters, where INVALID_HANDLE_VALUE is used as a sentry value to indicate errors, such as in the return value of CreateFileW. This uses repr(transparent) and has the representation of a host handle, so that it can be used in such FFI declarations.
  • InvalidHandleError
    This is the error type used by HandleOrInvalid when attempting to convert into a handle, to indicate that the value is INVALID_HANDLE_VALUE.
  • NullHandleError
    This is the error type used by HandleOrNull when attempting to convert into a handle, to indicate that the value is null.
  • OwnedHandle
    An owned handle.
  • OwnedSocket
    An owned socket.

Traits

  • AsFilelike
    A portable trait to borrow a reference from an underlying filelike object.
  • AsHandle
    A trait to borrow the handle from an underlying object.
  • AsSocket
    A trait to borrow the socket from an underlying object.
  • AsSocketlike
    A portable trait to borrow a reference from an underlying socketlike object.
  • FromFilelike
    A portable trait to express the ability to construct an object from a filelike object.
  • FromHandle
    A trait to express the ability to construct an object from a handle.
  • FromSocket
    A trait to express the ability to construct an object from a socket.
  • FromSocketlike
    A portable trait to express the ability to construct an object from a socketlike object.
  • IntoFilelike
    A portable trait to express the ability to consume an object and acquire ownership of its filelike object.
  • IntoHandleDeprecated
    A trait to express the ability to consume an object and acquire ownership of its handle.
  • IntoSocketDeprecated
    A trait to express the ability to consume an object and acquire ownership of its socket.
  • IntoSocketlike
    A portable trait to express the ability to consume an object and acquire ownership of its socketlike object.

Type Definitions