diff --git a/doc/nonblock.BackgroundRead.html b/doc/nonblock.BackgroundRead.html index 5c5c7dd..fa6fd33 100644 --- a/doc/nonblock.BackgroundRead.html +++ b/doc/nonblock.BackgroundRead.html @@ -1,118 +1,118 @@ -Python: module nonblock.BackgroundRead - - +Python: module nonblock.BackgroundRead + + - - -
 
- 
nonblock.BackgroundRead
index
-

Copyright (c) 2015-2016 Timothy Savannah under terms of LGPLv2. You should have received a copy of this LICENSE with this distribution.

+ + +
 
+ 
nonblock.BackgroundRead
index
+

Copyright (c) 2015-2016 Timothy Savannah under terms of LGPLv2. You should have received a copy of this LICENSE with this distribution.

read.py Contains pure-python functions for non-blocking reads in python

-

- - - +

+

 
-Modules
+ + - -
 
+Modules
       
threading
-
time
-

- - - + +
 
-Classes
       
threading
+
time
+

+ + + - - +
 
+Classes
       
-
builtins.object -
-
-
BackgroundReadData +
       
+
builtins.object +
+
+
BackgroundReadData
-

- - - +

+

 
-class BackgroundReadData(builtins.object)
+ + - - - - + + +
 
+class BackgroundReadData(builtins.object)
   BackgroundReadData - An object returned by the bgread function. This object is automatically populated in the background by a thread with data read off the stream.

-It contains the following attributes:

-    blocks - The raw non-zero length blocks read from the stream, in order.

-    data - A calculated property, which is a bytes/str (depending on stream mode). It is the joining of all the read blocks, and contains all the data read to-date.

-    isFinished - starts False, and becomes True after all data has been read from the stream. Will remain False if there is an exception raised during I/O
-    
-    error - starts None, and is set to any exception that is raised during reading (which will also terminate the thread)
 
 Methods defined here:
-
__init__(self, dataType)
+
   BackgroundReadData(dataType)

+BackgroundReadData - An object returned by the bgread function. This object is automatically populated in the background by a thread with data read off the stream.

+It contains the following attributes:

+    blocks - The raw non-zero length blocks read from the stream, in order.

+    data - A calculated property, which is a bytes/str (depending on stream mode). It is the joining of all the read blocks, and contains all the data read to-date.

+    isFinished - starts False, and becomes True after all data has been read from the stream. Will remain False if there is an exception raised during I/O

+    error - starts None, and is set to any exception that is raised during reading (which will also terminate the thread)
 
 Methods defined here:
+
__init__(self, dataType)
Initialize self.  See help(type(self)) for accurate signature.
-
addBlock(self, block)
+
addBlock(self, block)
-
-Data descriptors defined here:
-
__dict__
-
dictionary for instance variables (if defined)
+
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
-
__weakref__
-
list of weak references to the object (if defined)
+
__weakref__
+
list of weak references to the object (if defined)
-
data
-
data - property to get the data as a string or bytes.
-    Use "blocks" to access the individual blocks of data

+
data
+
data - property to get the data as a string or bytes.
+    Use "blocks" to access the individual blocks of data

@return <str or bytes> - All data currently read, as a string or bytes (depending on the dataType)
-

- - - +
 
-Functions

+ + + - -
 
+Functions
       
bgread(stream, blockSizeLimit=65535, pollTime=0.03, closeStream=True)
bgread - Start a thread which will read from the given stream in a non-blocking fashion, and automatically populate data in the returned object.

-    @param stream <object> - A stream on which to read. Socket, file, etc.

-    @param blockSizeLimit <None/int> - Number of bytes. Default 65535.

-        If None, the stream will be read from until there is no more available data (not closed, but you've read all that's been flushed to straem). This is okay for smaller datasets, but this number effectively controls the amount of CPU time spent in I/O on this stream VS everything else in your application. The default of 65535 bytes is a fair amount of data.

-    @param pollTime <float> - Default .03 (30ms) After all available data has been read from the stream, wait this many seconds before checking again for more data.
-        
-        A low number here means a high priority, i.e. more cycles will be devoted to checking and collecting the background data. Since this is a non-blocking read, this value is the "block", which will return execution context to the remainder of the application. The default of 100ms should be fine in most cases. If it's really idle data collection, you may want to try a value of 1 second.

-    @param closeStream <bool> - Default True. If True, the "close" method on the stream object will be called when the other side has closed and all data has been read.



-NOTES --

-        blockSizeLimit / pollTime is your effective max-throughput. Real throughput will be lower than this number, as the actual throughput is be defined by:

-        T = (blockSizeLimit / pollTime) - DeviceReadTime(blockSizeLimit)

-    Using the defaults of .03 and 65535 means you'll read up to 2 MB per second. Keep in mind that the more time spent in I/O means less time spent doing other tasks.


-    @return - The return of this function is a BackgroundReadData object. This object contains an attribute "blocks" which is a list of the non-zero-length blocks that were read from the stream. The object also contains a calculated property, "data", which is a string/bytes (depending on stream mode) of all the data currently read. The property "isFinished" will be set to True when the stream has been closed. The property "error" will be set to any exception that occurs during reading which will terminate the thread. @see BackgroundReadData for more info.
-

- - - + +
 
-Data
       
bgread(stream, blockSizeLimit=65535, pollTime=0.03, closeStream=True)
bgread - Start a thread which will read from the given stream in a non-blocking fashion, and automatically populate data in the returned object.

+    @param stream <object> - A stream on which to read. Socket, file, etc.

+    @param blockSizeLimit <None/int> - Number of bytes. Default 65535.

+        If None, the stream will be read from until there is no more available data (not closed, but you've read all that's been flushed to straem). This is okay for smaller datasets, but this number effectively controls the amount of CPU time spent in I/O on this stream VS everything else in your application. The default of 65535 bytes is a fair amount of data.

+    @param pollTime <float> - Default .03 (30ms) After all available data has been read from the stream, wait this many seconds before checking again for more data.

+        A low number here means a high priority, i.e. more cycles will be devoted to checking and collecting the background data. Since this is a non-blocking read, this value is the "block", which will return execution context to the remainder of the application. The default of 100ms should be fine in most cases. If it's really idle data collection, you may want to try a value of 1 second.

+    @param closeStream <bool> - Default True. If True, the "close" method on the stream object will be called when the other side has closed and all data has been read.



+NOTES --

+        blockSizeLimit / pollTime is your effective max-throughput. Real throughput will be lower than this number, as the actual throughput is be defined by:

+        T = (blockSizeLimit / pollTime) - DeviceReadTime(blockSizeLimit)

+    Using the defaults of .03 and 65535 means you'll read up to 2 MB per second. Keep in mind that the more time spent in I/O means less time spent doing other tasks.


+    @return - The return of this function is a BackgroundReadData object. This object contains an attribute "blocks" which is a list of the non-zero-length blocks that were read from the stream. The object also contains a calculated property, "data", which is a string/bytes (depending on stream mode) of all the data currently read. The property "isFinished" will be set to True when the stream has been closed. The property "error" will be set to any exception that occurs during reading which will terminate the thread. @see BackgroundReadData for more info.
+

+ + + - -
 
+Data
       __all__ = ('BackgroundReadData', 'bgread')
- +        +__all__ = ('BackgroundReadData', 'bgread') +

\ No newline at end of file diff --git a/doc/nonblock.BackgroundWrite.html b/doc/nonblock.BackgroundWrite.html index df4b321..611d92b 100644 --- a/doc/nonblock.BackgroundWrite.html +++ b/doc/nonblock.BackgroundWrite.html @@ -1,276 +1,275 @@ -Python: module nonblock.BackgroundWrite - - +Python: module nonblock.BackgroundWrite + + - - -
 
- 
nonblock.BackgroundWrite
index
-

Copyright (c) 2015, 2016, 2017 Timothy Savannah under terms of LGPLv2. You should have received a copy of this LICENSE with this distribution.

+ + +
 
+ 
nonblock.BackgroundWrite
index
+

Copyright (c) 2015, 2016, 2017 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
+ + - -
 
+Modules
       
sys
-
threading
-
time
-

- - - + +
 
-Classes
       
threading
+
time
+

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

- - - +

+

 
-class BackgroundIOPriority(builtins.object)
+ + - - - - + + +
 
+class BackgroundIOPriority(builtins.object)
   BackgroundIOPriority - Priority Profile for doing background writes.

-    See __init__ for fields
 
 Methods defined here:
-
__getitem__(self, key)
+
   BackgroundIOPriority(chainPollTime, defaultChunkSize, bandwidthPct, numChunksRateSmoothing=5)

+BackgroundIOPriority - Priority Profile for doing background writes.

+    See __init__ for fields
 
 Methods defined here:
+
__getitem__(self, key)
-
__init__(self, chainPollTime, defaultChunkSize, bandwidthPct, numChunksRateSmoothing=5)
__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 bandwidthPct - integer > 0 and < 100. This is the percentage of overall bandwidth that this task will attempt to use.

-  A high number means higher throughput at the cost of lest interactivity for other tasks, a low number means the opposite.

-  So, for example, a bandwidthPct of "50" will attempt to use "50%" of the available bandwidth. Note, this does not represent theroetical
-  max bandwidth, i.e. the max rate of the I/O device, but the amount of available bandwidth available to this application. For example,
-  if this is given "100%", no throttling is performed. If this is given "80%", then it calculates the average time to write a single chunk,
-  ( see #numChunksRateSmoothing for how many chunks are used in evaluating this average ), and sleeps for then 20% of that time at the end
-  of every chunk. 

-@param numChunksRateSmoothing - integer >= 1 , Default 5. This is the number of chunks which are used in calculating the current throughput rate.
-  See #bandwidthPct for the other half of the story. The higher this number, the more "fair" your application will be against a constant
-  rate of I/O by other applications, but the less able it may be to play fair when the external I/O is spiking.

-  Also, consider that this is related to the #defaultChunkSize, as it is not a constant period of time. The default of "5" should be okay,
-  but you may want to tune it if you use really large or really small chunk sizes.


+
__init__(self, chainPollTime, defaultChunkSize, bandwidthPct, numChunksRateSmoothing=5)
__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 bandwidthPct - integer > 0 and < 100. This is the percentage of overall bandwidth that this task will attempt to use.

+  A high number means higher throughput at the cost of lest interactivity for other tasks, a low number means the opposite.

+  So, for example, a bandwidthPct of "50" will attempt to use "50%" of the available bandwidth. Note, this does not represent theroetical
+  max bandwidth, i.e. the max rate of the I/O device, but the amount of available bandwidth available to this application. For example,
+  if this is given "100%", no throttling is performed. If this is given "80%", then it calculates the average time to write a single chunk,
+  ( see #numChunksRateSmoothing for how many chunks are used in evaluating this average ), and sleeps for then 20% of that time at the end
+  of every chunk.

+@param numChunksRateSmoothing - integer >= 1 , Default 5. This is the number of chunks which are used in calculating the current throughput rate.
+  See #bandwidthPct for the other half of the story. The higher this number, the more "fair" your application will be against a constant
+  rate of I/O by other applications, but the less able it may be to play fair when the external I/O is spiking.

+  Also, consider that this is related to the #defaultChunkSize, as it is not a constant period of time. The default of "5" should be okay,
+  but you may want to tune it if you use really large or really small chunk sizes.


An "interactivity score" is defined to be (number of calculations) / (time to write data).
-
__setitem__(self, key, value)
+
__setitem__(self, key, value)
-
-Data descriptors defined here:
-
bandwidthPct
+
+Data descriptors defined here:
+
bandwidthPct
-
chainPollTime
+
chainPollTime
-
defaultChunkSize
+
defaultChunkSize
-
numChunksRateSmoothing
+
numChunksRateSmoothing
-

- - - +
 
-class BackgroundWriteProcess(threading.Thread)

+ + + - - - - + + +
 
+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
+
   BackgroundWriteProcess(fileObj, dataBlocks, closeWhenFinished=False, chainAfter=None, ioPrio=4)

+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
+
+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.
+
run(self)
run - Starts the thread. bgwrite and bgwrite_chunk automatically start the thread.
-
-Methods inherited from threading.Thread:
-
__repr__(self)
Return repr(self).
+
+Methods inherited from threading.Thread:
+
__repr__(self)
Return repr(self).
-
getName(self)
+
getName(self)
-
isAlive = is_alive(self)
Return whether the thread is alive.

-This method returns True just before the run() method starts until just
-after the run() method terminates. The module function enumerate()
-returns a list of all alive threads.
+
isAlive(self)
Return whether the thread is alive.

+This method is deprecated, use is_alive() instead.
-
isDaemon(self)
+
isDaemon(self)
-
is_alive(self)
Return whether the thread is alive.

-This method returns True just before the run() method starts until just
-after the run() method terminates. The module function enumerate()
+
is_alive(self)
Return whether the thread is alive.

+This method returns True just before the run() method starts until just
+after the run() method terminates. The module function enumerate()
returns a list of all alive threads.
-
join(self, timeout=None)
Wait until the thread terminates.

-This blocks the calling thread until the thread whose join() method is
-called terminates -- either normally or through an unhandled exception
-or until the optional timeout occurs.

-When the timeout argument is present and not None, it should be a
-floating point number specifying a timeout for the operation in seconds
-(or fractions thereof). As join() always returns None, you must call
-isAlive() after join() to decide whether a timeout happened -- if the
-thread is still alive, the join() call timed out.

-When the timeout argument is not present or None, the operation will
-block until the thread terminates.

-A thread can be join()ed many times.

-join() raises a RuntimeError if an attempt is made to join the current
-thread as that would cause a deadlock. It is also an error to join() a
-thread before it has been started and attempts to do so raises the same
+
join(self, timeout=None)
Wait until the thread terminates.

+This blocks the calling thread until the thread whose join() method is
+called terminates -- either normally or through an unhandled exception
+or until the optional timeout occurs.

+When the timeout argument is present and not None, it should be a
+floating point number specifying a timeout for the operation in seconds
+(or fractions thereof). As join() always returns None, you must call
+is_alive() after join() to decide whether a timeout happened -- if the
+thread is still alive, the join() call timed out.

+When the timeout argument is not present or None, the operation will
+block until the thread terminates.

+A thread can be join()ed many times.

+join() raises a RuntimeError if an attempt is made to join the current
+thread as that would cause a deadlock. It is also an error to join() a
+thread before it has been started and attempts to do so raises the same
exception.
-
setDaemon(self, daemonic)
+
setDaemon(self, daemonic)
-
setName(self, name)
+
setName(self, name)
-
start(self)
Start the thread's activity.

-It must be called at most once per thread object. It arranges for the
-object's run() method to be invoked in a separate thread of control.

-This method will raise a RuntimeError if called more than once on the
-same thread object.
+
start(self)
Start the thread's activity.

+It must be called at most once per thread object. It arranges for the
+object's run() method to be invoked in a separate thread of control.

+This method will raise a RuntimeError if called more than once on the
+same thread object.
-
-Data descriptors inherited from threading.Thread:
-
__dict__
-
dictionary for instance variables (if defined)
+
+Data descriptors inherited from threading.Thread:
+
__dict__
+
dictionary for instance variables (if defined)
-
__weakref__
-
list of weak references to the object (if defined)
+
__weakref__
+
list of weak references to the object (if defined)
-
daemon
-
A boolean value indicating whether this thread is a daemon thread.

-This must be set before start() is called, otherwise RuntimeError is
-raised. Its initial value is inherited from the creating thread; the
-main thread is not a daemon thread and therefore all threads created in
-the main thread default to daemon = False.

-The entire Python program exits when no alive non-daemon threads are
+
daemon
+
A boolean value indicating whether this thread is a daemon thread.

+This must be set before start() is called, otherwise RuntimeError is
+raised. Its initial value is inherited from the creating thread; the
+main thread is not a daemon thread and therefore all threads created in
+the main thread default to daemon = False.

+The entire Python program exits when no alive non-daemon threads are
left.
-
ident
-
Thread identifier of this thread or None if it has not been started.

-This is a nonzero integer. See the thread.get_ident() function. Thread
-identifiers may be recycled when a thread exits and another thread is
+
ident
+
Thread identifier of this thread or None if it has not been started.

+This is a nonzero integer. See the get_ident() function. Thread
+identifiers may be recycled when a thread exits and another thread is
created. The identifier is available even after the thread has exited.
-
name
-
A string used for identification purposes only.

-It has no semantics. Multiple threads may be given the same name. The
+
name
+
A string used for identification purposes only.

+It has no semantics. Multiple threads may be given the same name. The
initial name is set by the constructor.
-

- - - +
 
-Functions

+ + + - - +
 
+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

+
       
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"]
-

- - - +
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

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

\ No newline at end of file diff --git a/doc/nonblock.common.html b/doc/nonblock.common.html index 12ff5d7..960d062 100644 --- a/doc/nonblock.common.html +++ b/doc/nonblock.common.html @@ -1,35 +1,33 @@ -Python: module nonblock.common - - +Python: module nonblock.common + + - - -
 
- 
nonblock.common
index
-

-

- - - +
 
-Functions
+ +
 
+ 
nonblock.common
index
+

+

+ + + - - +
 
+Functions
       
detect_stream_mode(stream)
detect_stream_mode - Detect the mode on a given stream

-    @param stream <object> - A stream object

-    If "mode" is present, that will be used.

+
       
detect_stream_mode(stream)
detect_stream_mode - Detect the mode on a given stream

+    @param stream <object> - A stream object

+    If "mode" is present, that will be used.

@return <type> - "Bytes" type or "str" type
-

- - - +
 
-Data

+ + + - -
 
+Data
       __all__ = ('detect_stream_mode',)
- +        +__all__ = ('detect_stream_mode',) +

\ No newline at end of file diff --git a/doc/nonblock.html b/doc/nonblock.html index f25860c..ba8daab 100644 --- a/doc/nonblock.html +++ b/doc/nonblock.html @@ -1,173 +1,173 @@ -Python: package nonblock - - +Python: package nonblock + + - - -
 
- 
nonblock (version 4.0.0)
index
-

Copyright (c) 2015-2016 Timothy Savannah under terms of LGPLv2. You should have received a copy of this LICENSE with this distribution.

+ + +
 
+ 
nonblock (version 4.0.1)
index
+

Copyright (c) 2015-2016, 2017, 2019 Timothy Savannah under terms of LGPLv2. You should have received a copy of this LICENSE with this distribution.

Contains pure-python functions for non-blocking IO in python

-

- - - +

+

 
-Package Contents
+ + - -
 
+Package Contents
       
BackgroundRead
-
BackgroundWrite
-
common
-
read
-

- - - + +
 
-Classes
       
BackgroundRead
+
BackgroundWrite
+
common
+
read
+

+ + + - - +
 
+Classes
       
-
builtins.object -
-
-
nonblock.BackgroundWrite.BackgroundIOPriority +
       
+
builtins.object +
+
+
nonblock.BackgroundWrite.BackgroundIOPriority
-

- - - +

+

 
-class BackgroundIOPriority(builtins.object)
+ + - - - - + + +
 
+class BackgroundIOPriority(builtins.object)
   BackgroundIOPriority - Priority Profile for doing background writes.

-    See __init__ for fields
 
 Methods defined here:
-
__getitem__(self, key)
+
   BackgroundIOPriority(chainPollTime, defaultChunkSize, bandwidthPct, numChunksRateSmoothing=5)

+BackgroundIOPriority - Priority Profile for doing background writes.

+    See __init__ for fields
 
 Methods defined here:
+
__getitem__(self, key)
-
__init__(self, chainPollTime, defaultChunkSize, bandwidthPct, numChunksRateSmoothing=5)
__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 bandwidthPct - integer > 0 and < 100. This is the percentage of overall bandwidth that this task will attempt to use.

-  A high number means higher throughput at the cost of lest interactivity for other tasks, a low number means the opposite.

-  So, for example, a bandwidthPct of "50" will attempt to use "50%" of the available bandwidth. Note, this does not represent theroetical
-  max bandwidth, i.e. the max rate of the I/O device, but the amount of available bandwidth available to this application. For example,
-  if this is given "100%", no throttling is performed. If this is given "80%", then it calculates the average time to write a single chunk,
-  ( see #numChunksRateSmoothing for how many chunks are used in evaluating this average ), and sleeps for then 20% of that time at the end
-  of every chunk. 

-@param numChunksRateSmoothing - integer >= 1 , Default 5. This is the number of chunks which are used in calculating the current throughput rate.
-  See #bandwidthPct for the other half of the story. The higher this number, the more "fair" your application will be against a constant
-  rate of I/O by other applications, but the less able it may be to play fair when the external I/O is spiking.

-  Also, consider that this is related to the #defaultChunkSize, as it is not a constant period of time. The default of "5" should be okay,
-  but you may want to tune it if you use really large or really small chunk sizes.


+
__init__(self, chainPollTime, defaultChunkSize, bandwidthPct, numChunksRateSmoothing=5)
__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 bandwidthPct - integer > 0 and < 100. This is the percentage of overall bandwidth that this task will attempt to use.

+  A high number means higher throughput at the cost of lest interactivity for other tasks, a low number means the opposite.

+  So, for example, a bandwidthPct of "50" will attempt to use "50%" of the available bandwidth. Note, this does not represent theroetical
+  max bandwidth, i.e. the max rate of the I/O device, but the amount of available bandwidth available to this application. For example,
+  if this is given "100%", no throttling is performed. If this is given "80%", then it calculates the average time to write a single chunk,
+  ( see #numChunksRateSmoothing for how many chunks are used in evaluating this average ), and sleeps for then 20% of that time at the end
+  of every chunk.

+@param numChunksRateSmoothing - integer >= 1 , Default 5. This is the number of chunks which are used in calculating the current throughput rate.
+  See #bandwidthPct for the other half of the story. The higher this number, the more "fair" your application will be against a constant
+  rate of I/O by other applications, but the less able it may be to play fair when the external I/O is spiking.

+  Also, consider that this is related to the #defaultChunkSize, as it is not a constant period of time. The default of "5" should be okay,
+  but you may want to tune it if you use really large or really small chunk sizes.


An "interactivity score" is defined to be (number of calculations) / (time to write data).
-
__setitem__(self, key, value)
+
__setitem__(self, key, value)
-
-Data descriptors defined here:
-
bandwidthPct
+
+Data descriptors defined here:
+
bandwidthPct
-
chainPollTime
+
chainPollTime
-
defaultChunkSize
+
defaultChunkSize
-
numChunksRateSmoothing
+
numChunksRateSmoothing
-

- - - +
 
-Functions

+ + + - - +
 
+Functions
       
bgread(stream, blockSizeLimit=65535, pollTime=0.03, closeStream=True)
bgread - Start a thread which will read from the given stream in a non-blocking fashion, and automatically populate data in the returned object.

-    @param stream <object> - A stream on which to read. Socket, file, etc.

-    @param blockSizeLimit <None/int> - Number of bytes. Default 65535.

-        If None, the stream will be read from until there is no more available data (not closed, but you've read all that's been flushed to straem). This is okay for smaller datasets, but this number effectively controls the amount of CPU time spent in I/O on this stream VS everything else in your application. The default of 65535 bytes is a fair amount of data.

-    @param pollTime <float> - Default .03 (30ms) After all available data has been read from the stream, wait this many seconds before checking again for more data.
-        
-        A low number here means a high priority, i.e. more cycles will be devoted to checking and collecting the background data. Since this is a non-blocking read, this value is the "block", which will return execution context to the remainder of the application. The default of 100ms should be fine in most cases. If it's really idle data collection, you may want to try a value of 1 second.

-    @param closeStream <bool> - Default True. If True, the "close" method on the stream object will be called when the other side has closed and all data has been read.



-NOTES --

-        blockSizeLimit / pollTime is your effective max-throughput. Real throughput will be lower than this number, as the actual throughput is be defined by:

-        T = (blockSizeLimit / pollTime) - DeviceReadTime(blockSizeLimit)

-    Using the defaults of .03 and 65535 means you'll read up to 2 MB per second. Keep in mind that the more time spent in I/O means less time spent doing other tasks.


-    @return - The return of this function is a BackgroundReadData object. This object contains an attribute "blocks" which is a list of the non-zero-length blocks that were read from the stream. The object also contains a calculated property, "data", which is a string/bytes (depending on stream mode) of all the data currently read. The property "isFinished" will be set to True when the stream has been closed. The property "error" will be set to any exception that occurs during reading which will terminate the thread. @see BackgroundReadData for more info.
-
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

+
       
bgread(stream, blockSizeLimit=65535, pollTime=0.03, closeStream=True)
bgread - Start a thread which will read from the given stream in a non-blocking fashion, and automatically populate data in the returned object.

+    @param stream <object> - A stream on which to read. Socket, file, etc.

+    @param blockSizeLimit <None/int> - Number of bytes. Default 65535.

+        If None, the stream will be read from until there is no more available data (not closed, but you've read all that's been flushed to straem). This is okay for smaller datasets, but this number effectively controls the amount of CPU time spent in I/O on this stream VS everything else in your application. The default of 65535 bytes is a fair amount of data.

+    @param pollTime <float> - Default .03 (30ms) After all available data has been read from the stream, wait this many seconds before checking again for more data.

+        A low number here means a high priority, i.e. more cycles will be devoted to checking and collecting the background data. Since this is a non-blocking read, this value is the "block", which will return execution context to the remainder of the application. The default of 100ms should be fine in most cases. If it's really idle data collection, you may want to try a value of 1 second.

+    @param closeStream <bool> - Default True. If True, the "close" method on the stream object will be called when the other side has closed and all data has been read.



+NOTES --

+        blockSizeLimit / pollTime is your effective max-throughput. Real throughput will be lower than this number, as the actual throughput is be defined by:

+        T = (blockSizeLimit / pollTime) - DeviceReadTime(blockSizeLimit)

+    Using the defaults of .03 and 65535 means you'll read up to 2 MB per second. Keep in mind that the more time spent in I/O means less time spent doing other tasks.


+    @return - The return of this function is a BackgroundReadData object. This object contains an attribute "blocks" which is a list of the non-zero-length blocks that were read from the stream. The object also contains a calculated property, "data", which is a string/bytes (depending on stream mode) of all the data currently read. The property "isFinished" will be set to True when the stream has been closed. The property "error" will be set to any exception that occurs during reading which will terminate the thread. @see BackgroundReadData for more info.
+
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.
-
nonblock_read(stream, limit=None, forceMode=None)
nonblock_read - Read any data available on the given stream (file, socket, etc) without blocking and regardless of newlines.

-    @param stream <object> - A stream (like a file object or a socket)
-    @param limit <None/int> - Max number of bytes to read. If None or 0, will read as much data is available.
-    @param forceMode <None/mode string> - Default None. Will be autodetected if None. If you want to explicitly force a mode, provide 'b' for binary (bytes) or 't' for text (Str). This determines the return type.

+
nonblock_read(stream, limit=None, forceMode=None)
nonblock_read - Read any data available on the given stream (file, socket, etc) without blocking and regardless of newlines.

+    @param stream <object> - A stream (like a file object or a socket)
+    @param limit <None/int> - Max number of bytes to read. If None or 0, will read as much data is available.
+    @param forceMode <None/mode string> - Default None. Will be autodetected if None. If you want to explicitly force a mode, provide 'b' for binary (bytes) or 't' for text (Str). This determines the return type.

    @return <str or bytes depending on stream's mode> - Any data available on the stream, or "None" if the stream was closed on the other side and all data has already been read.
-

- - - +
 
-Data

+ + + - -
 
+Data
       __all__ = ('nonblock_read', 'bgwrite', 'bgwrite_chunk', 'BackgroundIOPriority', 'bgread')
- +        +__all__ = ('nonblock_read', 'bgwrite', 'bgwrite_chunk', 'BackgroundIOPriority', 'bgread') +

\ No newline at end of file diff --git a/doc/nonblock.read.html b/doc/nonblock.read.html index d4ba16a..2ded8fc 100644 --- a/doc/nonblock.read.html +++ b/doc/nonblock.read.html @@ -1,45 +1,43 @@ -Python: module nonblock.read - - +Python: module nonblock.read + + - - -
 
- 
nonblock.read
index
-

Copyright (c) 2015-2016 Timothy Savannah under terms of LGPLv2. You should have received a copy of this LICENSE with this distribution.

+ + +
 
+ 
nonblock.read
index
+

Copyright (c) 2015-2016 Timothy Savannah under terms of LGPLv2. You should have received a copy of this LICENSE with this distribution.

read.py Contains pure-python functions for non-blocking reads in python

-

- - - +

+

 
-Modules
+ + - -
 
+Modules
       
select
-

- - - + +
 
-Functions
       
select
+

+ + + - - +
 
+Functions
       
nonblock_read(stream, limit=None, forceMode=None)
nonblock_read - Read any data available on the given stream (file, socket, etc) without blocking and regardless of newlines.

-    @param stream <object> - A stream (like a file object or a socket)
-    @param limit <None/int> - Max number of bytes to read. If None or 0, will read as much data is available.
-    @param forceMode <None/mode string> - Default None. Will be autodetected if None. If you want to explicitly force a mode, provide 'b' for binary (bytes) or 't' for text (Str). This determines the return type.

+
       
nonblock_read(stream, limit=None, forceMode=None)
nonblock_read - Read any data available on the given stream (file, socket, etc) without blocking and regardless of newlines.

+    @param stream <object> - A stream (like a file object or a socket)
+    @param limit <None/int> - Max number of bytes to read. If None or 0, will read as much data is available.
+    @param forceMode <None/mode string> - Default None. Will be autodetected if None. If you want to explicitly force a mode, provide 'b' for binary (bytes) or 't' for text (Str). This determines the return type.

    @return <str or bytes depending on stream's mode> - Any data available on the stream, or "None" if the stream was closed on the other side and all data has already been read.
-

- - - +
 
-Data

+ + + - -
 
+Data
       __all__ = ('nonblock_read',)
- +        +__all__ = ('nonblock_read',) +

\ No newline at end of file