Struct Table

pub struct Table<K, E>
where
    K: Key + Ord + Borrow<<K as Key>::Borrowed>,
    <K as Key>::Borrowed: Ord + ToOwned<Owned = K>,
    E: Entry,
    E::Metadata: TableMetadata,
{ /* private fields */ }

A table exported to other plugins

An instance of this type can be exposed to other plugins via tables::TablesInput::add_table

The generic parameters are: key type and entry type. The key type is anything usable as a table key, while the entry type is a type that can be stored in the table. You can obtain such a type by #[derive]ing Entry on a struct describing all the table fields.

Supported key types include:

• integer types (u8/i8, u16/i16, u32/i32, u64/i64)
• crate::tables::import::Bool (an API equivalent of bool)
• &CStr (spelled as just CStr when used as a generic argument)

See crate::tables::export for details.

The implementation is thread-safe when the thread-safe-tables feature is enabled.

Implementations

impl<K, E> Table<K, E>

where K: Key + Ord + Borrow<<K as Key>::Borrowed>, <K as Key>::Borrowed: Ord + ToOwned<Owned = K>, E: Entry, E::Metadata: TableMetadata,

pub fn new_with_metadata( tag: &'static CStr, metadata: &RefShared<ExtensibleEntryMetadata<<E as HasMetadata>::Metadata>>, ) -> Result<Self, Error>

Create a new table using provided metadata

This is only expected to be used by the derive macro.

pub fn new(name: &'static CStr) -> Result<Self, Error>

Create a new table

pub fn data(&self) -> RefShared<BTreeMap<K, RefShared<ExtensibleEntry<E>>>>

Get an accessor to the underlying data

This method returns a reference to the underlying BTreeMap, containing all the table’s data. It can be useful for:

• accessing the table from a different thread (with the thread-safe-tables feature enabled)
• bypassing the table API for convenience or more control over locking

To actually access the BTreeMap, you first need to lock the returned object for reading (data.read()) or writing (data.write()).

pub fn name(&self) -> &'static CStr

Return the table name.

pub fn size(&self) -> usize

Return the number of entries in the table.

pub fn lookup<Q>( &self, key: &Q, ) -> Option<ArcRwLockWriteGuard<RawRwLock, ExtensibleEntry<E>>>

where K: Borrow<Q>, Q: Ord + ?Sized,

Get an entry corresponding to a particular key.

pub fn get_field_value( &self, entry: &ArcRwLockWriteGuard<RawRwLock, ExtensibleEntry<E>>, field: &FieldDescriptor, out: &mut ss_plugin_state_data, ) -> Result<(), Error>

Get the value for a field in an entry.

pub fn iterate_entries<F>(&mut self, func: F) -> bool

where F: FnMut(&mut ArcRwLockWriteGuard<RawRwLock, ExtensibleEntry<E>>) -> bool,

Execute a closure on all entries in the table with read-only access.

The iteration continues until all entries are visited or the closure returns false.

pub fn clear(&mut self)

Remove all entries from the table.

pub fn erase<Q>( &mut self, key: &Q, ) -> Option<ArcRwLockWriteGuard<RawRwLock, ExtensibleEntry<E>>>

where K: Borrow<Q>, Q: Ord + ?Sized,

Erase an entry by key.

pub fn create_entry( &self, ) -> Result<ArcRwLockWriteGuard<RawRwLock, ExtensibleEntry<E>>, Error>

Create a new table entry.

This is a detached entry that can be later inserted into the table using Table::insert.

pub fn create_entry_fn( &self, ) -> impl Fn() -> Result<RefShared<ExtensibleEntry<E>>, Error>

Return a closure for creating table entries

The Table object itself cannot be shared between threads safely even with the thread-safe-tables feature enabled, but almost full functionality can be achieved using two objects that can:

1. The underlying BTreeMap, obtained from Table::data
2. A closure capable of creating a new entry (returned from this function)

The only functionality missing is listing table fields, and until a use case comes along, it’s likely to remain unimplemented.

The entry obtained by calling the closure returned from create_entry_fn can be later inserted into the table e.g. by calling BTreeMap::insert.

To actually access the entry’s fields, you first need to lock the returned object for reading (data.read()) or writing (data.write()).

pub fn insert<Q>( &mut self, key: &Q, entry: ArcRwLockWriteGuard<RawRwLock, ExtensibleEntry<E>>, ) -> Option<ArcRwLockWriteGuard<RawRwLock, ExtensibleEntry<E>>>

where K: Borrow<Q>, Q: Ord + ToOwned<Owned = K> + ?Sized,

Attach an entry to a table key

pub fn write( &self, entry: &mut ArcRwLockWriteGuard<RawRwLock, ExtensibleEntry<E>>, field: &FieldDescriptor, value: &ss_plugin_state_data, ) -> Result<(), Error>

Write a value to a field of an entry

pub fn list_fields(&mut self) -> &[ss_plugin_table_fieldinfo]

Return a list of fields as a slice of raw FFI objects

pub fn get_field( &self, name: &CStr, field_type: FieldTypeId, ) -> Option<FieldRef>

Return a field descriptor for a particular field

The requested field_type must match the actual type of the field

pub fn add_field( &mut self, name: &CStr, field_type: FieldTypeId, read_only: bool, ) -> Option<FieldRef>

Add a new field to the table

Trait Implementations

impl<K, E> Debug for Table<K, E>

where K: Key + Ord + Debug + Borrow<<K as Key>::Borrowed>, <K as Key>::Borrowed: Ord + ToOwned<Owned = K>, E: Entry + Debug, E::Metadata: TableMetadata + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.