nonblock.BackgroundWrite
index

Copyright (c) 2015 Timothy Savannah under terms of LGPLv2. You should have received a copy of this LICENSE with this distribution.
 
BackgroundWrite.py Contains pure-python functions for non-blocking background writing (writing multiple streams at once; interactive writing allowing a high amount of CPU time for calculations/other tasks

 
Modules
       
threading
time

 
Classes
       
builtins.object
BackgroundIOPriority
threading.Thread(builtins.object)
BackgroundWriteProcess

 
class BackgroundIOPriority(builtins.object)
    BackgroundIOPriority - Priority Profile for doing background writes.
 
    See __init__ for fields
 
  Methods defined here:
__getitem__(self, key)
__init__(self, chainPollTime, defaultChunkSize, priorityPct, charityRate=1.85, charityTime=0.0003)
__init__ - Create a BackgroundIOPriority
 
Some terms: throughput - Bandwidth out (Megs per second)
            interactivity - CPU time available for other tasks (calculations, other I/O, etc)
 
@param chainPollTime - float > 0, When chaining, this is the sleep time between checking if prior is finished.
    Too low and the polling takes up CPU time, too high and you'll lose a little time in between chained writes, while gaining interactivity elsewhere.
 
@param defaultChunkSize - integer > 0, When providing a straight string/bytes to bgwrite (instead of chunking yourself, or using bgwrite_chunk) this will
    be used as the max size of each chunk. Each chunk is written and a flush is issued (if the stream supports it).
    Increasing this increases throughput while decreasing interactivity
 
@param priorityPct - integer > 0, generally 0-100. When this number is high, throughput for the operation will be higher. When it is lower,
   interactivity is higher, e.x. if you have a calculation going and a write going, the lower this number the longer the write will take, but the more
   calculations will be performed during that period.
 
@param charityRate - float >= 0, Every couple of blocks written, the current throughput is checked and if things have been going swiftly
   a short sleep will be incurred. Increasing this number causes that check to happen more often.
 
   This number is related to both the number of blocks and the priorityPct. The default, should be fine, but you may find it better
   as a different value in certain cases. Increasing or decreasing could either increase or decrease interactivity, depending on those other factors.
   Generally, however, increasing this increases interactivity and ability to write in parallel, at the cost of throughput.
 
@param charityTime - float >= 0 - Used to calculate the time to sleep when the charity period hits. The equation is:
    sleepTime = charityTime * ((dataWritten / delta) / ( (dataWritten / delta) * priorityPctDec))
     Where dataWritten = number of bytes written already, delta = total time spent writing (not including charity time sleeping)
     and priorityPctDec = priorityPct / 100.
 
     Increasing this can increase interactivity and allow more parallel operations at the cost of throughput.
     The default should be fine for the majority of cases, but it is tunable.
 
An "interactivity score" is defined to be (number of calculations) / (time to write data).
__setitem__(self, key, value)

Data descriptors defined here:
chainPollTime
charityRate
charityTime
defaultChunkSize
priorityPct

 
class BackgroundWriteProcess(threading.Thread)
    BackgroundWriteProcess - A thread and data store representing a background write task. You should probably use one of the bgwrite* methods and not this directly.
 
Attributes:
 
    remainingData  <deque> - A queue representing the data yet to be written
 
    startedWriting <bool>  - Starts False, changes to True when writing has started (thread has started and any pending prior chain has completed)
 
    finished    <bool>   - Starts False, changes to True after writing has completed, and if closeWhenFinished is True the handle is also closed.
 
 
Method resolution order:
BackgroundWriteProcess
threading.Thread
builtins.object

Methods defined here:
__init__(self, fileObj, dataBlocks, closeWhenFinished=False, chainAfter=None, ioPrio=4)
__init__ - Create the BackgroundWriteProcess thread. You should probably use bgwrite or bgwrite_chunk instead of calling this directly.
 
@param fileObj <stream> - A stream, like a file, to write into. Hopefully it supports flushing, but it is not a requirement.
 
@param dataBlocks <bytes/str/list<bytes/str>> - If a list of bytes/str, those are treated as the data blocks, written in order with heuristics for interactivity in between blocks.  If bytes/str are provided not in a list form, they will be split based on the rules of the associated #ioPrio
 
@param closeWhenFinished <bool> - Default False. If True, the fileObj will be closed after writing has completed.
 
@param chainAfter <None/BackgroundWriteProcess> - If provided, will hold off writing until the provided BackgroundWriteProcess has completed (used for queueing multiple writes whilst retaining order)
 
@param ioPrio <int/BackgroundIOPriority> - If an integer (1-10), a predefined BackgroundIOPriority will be used. 1 is highest throughput, 10 is most interactivity. You can also pass in your own BackgroundIOPriority object if you want to define a custom profile.
 
 
@raises ValueError - If ioPrio is neither a BackgroundIOPriority nor integer 1-10 inclusive
                   - If chainAfter is not a BackgroundWriteProcess or None
run(self)
run - Starts the thread. bgwrite and bgwrite_chunk automatically start the thread.

 
Functions
       
bgwrite(fileObj, data, closeWhenFinished=False, chainAfter=None, ioPrio=4)
bgwrite - Start a background writing process
 
    @param fileObj <stream> - A stream backed by an fd
 
    @param data    <str/bytes/list> - The data to write. If a list is given, each successive element will be written to the fileObj and flushed. If a string/bytes is provided, it will be chunked according to the #BackgroundIOPriority chosen. If you would like a different chunking than the chosen ioPrio provides, use #bgwrite_chunk function instead.
 
       Chunking makes the data available quicker on the other side, reduces iowait on this side, and thus increases interactivity (at penalty of throughput).
 
    @param closeWhenFinished <bool> - If True, the given fileObj will be closed after all the data has been written. Default False.
 
    @param chainAfter  <None/BackgroundWriteProcess> - If a BackgroundWriteProcess object is provided (the return of bgwrite* functions), this data will be held for writing until the data associated with the provided object has completed writing.
    Use this to queue several background writes, but retain order within the resulting stream.
 
 
    @return - BackgroundWriteProcess - An object representing the state of this operation. @see BackgroundWriteProcess
bgwrite_chunk(fileObj, data, chunkSize, closeWhenFinished=False, chainAfter=None, ioPrio=4)
bgwrite_chunk - Chunk up the data into even #chunkSize blocks, and then pass it onto #bgwrite.
    Use this to break up a block of data into smaller segments that can be written and flushed.
    The smaller the chunks, the more interactive (recipient gets data quicker, iowait goes down for you) at cost of throughput.
 
    bgwrite will automatically chunk according to the given ioPrio, but you can use this for finer-tuned control.
 
    @see bgwrite
 
@param data <string/bytes> - The data to chunk up
 
@param chunkSize <integer> - The max siZe of each chunk.
chunk_data(data, chunkSize)
chunk_data - Chunks a string/bytes into a list of string/bytes, each member up to #chunkSize in length.
 
e.x.    chunk_data("123456789", 2) = ["12", "34", "56", "78", "9"]

 
Data
        __all__ = ('BackgroundWriteProcess', 'BackgroundIOPriority', 'bgwrite', 'bgwrite_chunk', 'chunk_data')