dataport 0.1.0

Port abstractions for data types
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

// Copyright © 2026 Stephan Kunz
//! Module containing 'bind' type ports.

pub mod bound_value;
pub mod in_;
pub mod in_out;
pub mod out_;
mod sequence_number;

use crate::{
	PortCommons,
	any_port_value::AnyPortValue,
	bind::bound_value::{BoundValuePtr, BoundValueReadGuard, BoundValueWriteGuard},
	error::Error,
};

/// Trait for bind port types.
pub trait BindCommons: PortCommons {
	/// Binds this port to the port 'bound'.
	/// # Errors
	/// - [`Error::DataType`], if 'self' is not the same type 'T' as 'bound'.
	/// - [`Error::PortType`], if 'bound' is not a valid port type.
	fn use_from_bound(&mut self, bound: &dyn BindCommons) -> Result<(), Error>;

	/// Returns the change sequence number of this port.
	/// A value of '0' indicates, that the port has never contained any data.
	fn sequence_number(&self) -> u32;

	/// Returns a pointer to the ports value.
	fn value(&self) -> BoundValuePtr;
}

/// Trait for incoming bind port types.
pub trait BindIn<T: AnyPortValue>: BindCommons {
	/// Returns a clone/copy of the T.
	/// Therefore T must implement [`Clone`].
	/// # Errors
	/// - [`Error::DataType`], if 'self' is not the expected type 'T'.
	fn get(&self) -> Result<Option<T>, Error>
	where
		T: Clone;

	/// Returns an immutable guard to the ports value T.
	/// # Errors
	/// - [`Error::NotFound`], if port is not in port list.
	/// - [`Error::DataType`], if port is not the expected port type & type of T.
	fn read(&self) -> Result<BoundValueReadGuard<T>, Error>;

	/// Returns an immutable guard to the ports value T.
	/// # Errors
	/// - [`Error::IsLocked`], if port is locked.
	/// - [`Error::NotFound`], if port is not in port list.
	/// - [`Error::DataType`], if port is not the expected port type & type of T.
	fn try_read(&self) -> Result<BoundValueReadGuard<T>, Error>;
}

/// Trait for incoming and outgoing bind port types.
pub trait BindInOut<T: AnyPortValue>: BindIn<T> + BindOut<T> {
	/// Sets a new value to the T and returns the old T.
	/// # Errors
	/// - [`Error::DataType`], if 'self' is not the expected type 'T'.
	fn replace(&mut self, value: T) -> Result<Option<T>, Error>;

	/// Returns the T, removing it from the port.
	/// # Errors
	/// - [`Error::DataType`], if 'self' is not the expected type 'T'.
	fn take(&mut self) -> Result<Option<T>, Error>;
}

/// Trait for outgoing bind port types.
pub trait BindOut<T: AnyPortValue>: BindCommons {
	/// Sets a new value to the T.
	/// # Errors
	/// - [`Error::DataType`], if 'self' is not the expected type 'T'.
	fn set(&mut self, value: T) -> Result<(), Error>;

	/// Returns a mutable guard to the ports value T.
	/// # Errors
	/// - [`Error::NotFound`], if port is not in port list.
	/// - [`Error::DataType`], if port is not the expected port type & type of T.
	fn write(&mut self) -> Result<BoundValueWriteGuard<T>, Error>;

	/// Returns a mutable guard to the ports value T.
	/// # Errors
	/// - [`Error::IsLocked`], if port is locked.
	/// - [`Error::NotFound`], if port is not in port list.
	/// - [`Error::DataType`], if port is not the expected port type & type of T.
	fn try_write(&mut self) -> Result<BoundValueWriteGuard<T>, Error>;
}