Crate cycler[−][src]
This is a data synchronization system with 1 writer and N readers. All writers and readers can operate on the data at the same time and will access the most up to date version when they switch. This is accomplished by storing N + 2 copies of the data with the writer publishing new versions of the data. The purpose of this is to allow read threads to have an unchanging up to date copy of the main data while the writer can edit it at the same time.
Requirements
The data type must also implement both ReadAccess
and WriteAccess
otherwise the access functions won’t be available.
These types allow the reader to see a subset of the data, intended for hiding data only the writer needs like a change log for optimization of the copy.
If you don’t care about access restrictions you can set ReadAccess::Read
and WriteAccess::Write
to Self and there will be zero runtime cost as the compiler should optimize that out.
Optimization
The most optimal thing to do with regard to memory usage is to have a single reader. N + 2 copies of the data must exist because in the worst case scenario all N readers are reading separate copies and the writer is finalizing a write. In this case the N copies of the data that are being read are inaccessible to writes and the last updated index cannot be written to so there must be an additional copy. What this means is that if you only utilize a single writer and distribute that the minimum amount of memory will be used. The trade off is that if you have multiple reading loops that operate at differing rates all the loops will operate at the slowest speed. Adding readers does not increase the amount of data to copy and may only slightly increase the time between copy switches.
This also is based on the clone_from
idea to clone values which is not implemented by derive normally (Derivative can auto derive for you).
This is a major optimization chance in this case and you can test/track the changes to reduce copy time.
Modules
rw_lock_cycler | The RwLockCycler uses |
Traits
CyclerReader | This trait is implemented for the read half of a cycler. |
CyclerWriter | This trait is implemented for the write half of a cycler. |
CyclerWriterDefault | This trait enables the write half of the cycler to be moved to the next chunk by a default copy function.
Usually this function is |
CyclerWriterFn | This trait enables the write half of the cycler to move to the next block using a given clone function.
This function follows the signature of |
CyclerWriterMutFn | This trait enables the write half of the cycler to move to the next block using a clone function that takes a mutable reference to the previous block. This is not preferable as optimizations where the reader can read the previous block while it’s being cloned are not possible. The function arguments are (from, to) |
EnsureSend | Trait that can be implemented to ensure a type is send |
EnsureSync | Trait that can be implemented to ensure a type is sync |
ReadAccess | This trait should be implemented for any type that can be read from by a cycler.
This specifically allows for the separation of read and write data from the cycler readers and writers.
If this functionality is not needed then |
UniversalCyclerReader | This trait is a collection of all the primarily supported reader traits. Other traits may be added to this in the future but none will be taken away without a major version bump. Other traits may also be added that do not fall under this for more specific functionality. |
UniversalCyclerWriter | This trait is a collection of all the primarily supported writer traits.
Other traits may be added to this in the future but none will be taken away without a major version bump.
Other traits may also be added that do not fall under this for more specific functionality (ex: |
WriteAccess | This trait should be implemented for any type that can be written to by a cycler.
This specifically allows for the separation of read and write data from the cycler readers and writers.
If this functionality is not needed then |
Functions
build_multiple_reader | Creates a multi reader DefaultCycler, the amount of readers being |
build_multiple_reader_cloned | Creates a multi reader DefaultCycler with the initial value being cloned. |
build_multiple_reader_default | Creates a multi reader DefaultCycler with the initial value being default. |
build_single_reader | Creates a single reader DefaultCycler using |
build_single_reader_cloned | Creates a single reader DefaultCycler cloning |
build_single_reader_default | Creates a single reader DefaultCycler using default initial values for the slots. |
Type Definitions
DefaultCyclerReader | This is the currently most optimal cycler reader that implements |
DefaultCyclerWriter | This is the currently most optimal cycler writer that implements |