Struct Port

pub struct Port { /* private fields */ }

The port object represents a Haiku port

There are two types of ports: there are owned ports, which means that they are created with this API. An owned port will live as long as the Port object lives. Owned ports are created with the Ports::create() method. There are also borrowed ports. These are retrieved using Ports::find_port(). These ports will outlive the lifetime of the Port object.

In terms of usage safety, ports are very badly designed on Haiku. While a port does have an owning team, this merely means the port is deleted when the team is. It does not give any additional privileges. This means that anyone can read from every port, and even delete every port.

This API makes the assumption that there is one owner of a port. This owner can read from the port, and has control over closing it. Other actors should not (and cannot). This means that reading from a port is only possible if you own it. If you try to read from a port that you do not own, the library will panic. You do not need to be the owner to write to a port.

Implementations

impl Port

pub fn create(name: &str, capacity: i32) -> Result<Port>

Create a new port and take ownership of it

This method creates a new port and takes ownership of that port. The name parameter should be no more than 32 characters. The capacity should be zero or higher. On success you will get a new port object.

pub fn find(name: &str) -> Option<Port>

Find an existing port by name

If the port exists, this function will return a borrowed Port object. This means that the port will not be deleted when the object goes out of scope.

pub fn from_id(id: port_id) -> Option<Port>

Construct a borrowed port from id

If the port exists, this function will return a borrowed Port object. This means that the port will not be deleted when the object goes out of scope.

pub fn write(&self, type_code: i32, data: &[u8]) -> Result<()>

Write data to the port

The data is identified by a type_code and is sent as an array of bytes. If the port has already reached its maximum capacity, this operation will block until the message can be written.

pub fn try_write( &self, type_code: i32, data: &[u8], timeout: Duration, ) -> Result<()>

Attempt to write data to the port

The data is identified by a type_code and is sent as an array of bytes. If the port has already reached its maximum capacity, this operation will block until the message can be written, or until the timeout is reached. Set the timeout to 0 if you want to return immediately if the port is at capacity.

pub fn read(&self) -> Result<(i32, Vec<u8>)>

Read data from a port

This method reads the next message from the port. The data is returned as a tuple of a type code and a buffer. The method waits until there is a next message.

pub fn try_read(&self, timeout: Duration) -> Result<(i32, Vec<u8>)>

Attempt to read data from a port

This method reads the next message from the port. The data is returned as a tuple of a type code and a buffer. The method waits until there is a next message, or until when a timeout if reached. If you don’t want to wait for a message to come in, you can set the timeout to 0

pub fn close(&self) -> Result<()>

Close a port

When a port is closed, data can no longer be written to it. The message queue can still be read. Once a port is closed, it cannot be reopened.

pub fn get_count(&self) -> Result<usize>

Get the port count

This returns the number of items that are waiting to be processed.

pub fn get_info(&self) -> Result<PortInfo>

Get the port info

pub fn get_port_id(&self) -> port_id

Get the underlying port id

Trait Implementations

impl Clone for Port

fn clone(&self) -> Self

Create a borrowed clone of the Port

A clone is always borrowed, whether the original is owned or not. The implication is that you have to make sure that the original Port will outlive any of its clones, if you want to keep using any clones.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for Port

fn drop(&mut self)

Executes the destructor for this type.