Skip to content

Commit

Permalink
kvstore.py doc strings clean up (apache#5801)
Browse files Browse the repository at this point in the history 
* kvstore.py doc strings clean up

* fix pylint warnings

* Fixed comment

* More doc fixes
  • Loading branch information
@madjam
madjam authored Apr 19, 2017
1 parent 47ee5e8 commit 4b03a6a
Showing 1 changed file with 49 additions and 55 deletions.
104 changes: 49 additions & 55 deletions python/mxnet/kvstore.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

def _ctype_key_value(keys, vals):
"""
Return ctype arrays for the key-value args, for internal use.
Returns ctype arrays for the key-value args. For internal use.
"""
if isinstance(keys, int):
if isinstance(vals, NDArray):
Expand Down Expand Up @@ -49,7 +49,7 @@ def updater_handle(key, lhs_handle, rhs_handle, _):
class KVStore(object):
"""A key-value store for synchronization of values, over multiple devices."""
def __init__(self, handle):
"""Initialize a new KVStore.
"""Initializes a new KVStore.
Parameters
----------
Expand All @@ -65,20 +65,19 @@ def __del__(self):
check_call(_LIB.MXKVStoreFree(self.handle))

def init(self, key, value):
""" Initialize a single or a sequence of key-value pairs into the store.
""" Initializes a single or a sequence of key-value pairs into the store.
For each key, one must init it before push and pull.
Only worker 0's (rank == 0) data are used.
This function returns after data have been initialized successfully.
For each key, one must `init` it before calling `push` or `pull`.
When multiple workers invoke `init` for the same key, only
the value supplied by worker with rank `0` is used. This function returns
after data has been initialized successfully.
Parameters
----------
key : int or sequence of int
The keys.
value : NDArray or sequence of NDArray
The values.
Values corresponding to the Keys
Examples
--------
Expand All @@ -101,16 +100,12 @@ def init(self, key, value):
self.handle, mx_uint(len(ckeys)), ckeys, cvals))

def push(self, key, value, priority=0):
""" Push a single or a sequence of key-value pairs into the store.
Data consistency:
1. This function returns after adding an operator to the engine.
""" Pushes a single or a sequence of key-value pairs into the store.
2. `push` is always called after all previous push and pull on the same
key are finished
3. There is no synchronization between workers. One can use ``_barrier()``
This function returns immediately after adding an operator to the engine.
The actual operation is executed asynchronously after all previous `push`
and `pull` calls for the same input key(s) are finished.
There is no synchronization between workers. One can use ``_barrier()``
to sync all workers.
Parameters
Expand All @@ -119,12 +114,12 @@ def push(self, key, value, priority=0):
Keys
value : NDArray or list of NDArray or list of list of NDArray
According values
Values corresponding to the Keys
priority : int, optional
The priority of the push operation.
The higher the priority, the faster this action is likely
to be executed before other push actions.
Higher priority push operations are likely to be executed before
other push actions
Examples
--------
Expand Down Expand Up @@ -167,30 +162,29 @@ def push(self, key, value, priority=0):
ctypes.c_int(priority)))

def pull(self, key, out=None, priority=0):
""" Pull a single value or a sequence of values from the store.
Data consistency:
""" Pulls a single value or a sequence of values from the store.
1. This function returns after adding an operator to the engine. But any
further read on out will be blocked until it is finished.
This function returns immediately after adding an operator to the engine.
Subsequent attempts to read from the `out` variable will be blocked until the
pull operation completes.
2. `pull` is always called after all previous push and pull on the same
key are finished.
`pull` is executed asynchronously after all previous `push` and `pull` calls
for the same input key(s) are finished.
3. It pulls the newest value from the store.
The returned values are gauranteed to the latest values in the store.
Parameters
----------
key : int or list of int
Keys.
out: NDArray or list of NDArray or list of list of NDArray
According values.
Values corresponding to the Keys.
priority : int, optional
The priority of the push operation.
The higher the priority, the faster this action is likely
to be executed before other push actions.
The priority of the pull operation.
Higher priority pull operations are likely to be executed before
other pull actions
Examples
--------
Expand Down Expand Up @@ -230,10 +224,10 @@ def pull(self, key, out=None, priority=0):
ctypes.c_int(priority)))

def set_optimizer(self, optimizer):
"""Register an optimizer to the store
""" Registers an optimizer with the store.
If there are multiple machines, this process (should be a worker node)
will pack this optimizer and send it to all servers. It returns after
When there are multiple machines, this operation (invoked from a worker node)
will pack the optimizer and send it to all servers. It returns after
this action is done.
Parameters
Expand All @@ -258,7 +252,7 @@ def set_optimizer(self, optimizer):

@property
def type(self):
"""Get the type of this kvstore.
""" Returns the type of this kvstore.
Returns
-------
Expand All @@ -271,20 +265,20 @@ def type(self):

@property
def rank(self):
"""Get the rank of this worker node.
""" Returns the rank of this worker node.
Returns
-------
rank : int
The rank of this node, which is in [0, get_num_workers())
The rank of this node, which is in range [0, num_workers())
"""
rank = ctypes.c_int()
check_call(_LIB.MXKVStoreGetRank(self.handle, ctypes.byref(rank)))
return rank.value

@property
def num_workers(self):
"""Get the number of worker nodes.
"""Returns the number of worker nodes.
Returns
-------
Expand All @@ -296,7 +290,7 @@ def num_workers(self):
return size.value

def save_optimizer_states(self, fname):
"""Save optimizer (updater) state to file.
"""Saves optimizer (updater) state to file.
Parameters
----------
Expand All @@ -308,7 +302,7 @@ def save_optimizer_states(self, fname):
fout.write(self._updater.get_states())

def load_optimizer_states(self, fname):
"""Load optimizer (updater) state from file.
"""Loads optimizer (updater) state from file.
Parameters
----------
Expand All @@ -319,10 +313,10 @@ def load_optimizer_states(self, fname):
self._updater.set_states(open(fname, 'rb').read())

def _set_updater(self, updater):
"""Set a push updater into the store.
"""Sets a push updater into the store.
This function only changes the local store. Use set_optimizer for
multiple machines.
This function only changes the local store. When running on multiple machines one must
use `set_optimizer`.
Parameters
----------
Expand Down Expand Up @@ -354,22 +348,22 @@ def _set_updater(self, updater):


def _barrier(self):
"""Global barrier among all worker nodes.
"""Invokes global barrier among all worker nodes.
For example, assume there are n machines. We want to let machine 0 first
init the values, and then pull the initialized value to all machines. Before
pulling, we can place a barrier to guarantee that the initialization is
finished.
For example, assume there are `n` machines. We would like machine `0` to first
`init` the values and then have all the workers `pull` the initialized value.
Before pulling, we can place invoke `_barrier()` to guarantee that the
initialization is finished.
"""
check_call(_LIB.MXKVStoreBarrier(self.handle))

def _send_command_to_servers(self, head, body):
"""Send a command to all server nodes.
"""Sends a command to all server nodes.
Send a command to all server nodes, which will make each server node run
``KVStoreServer.controller``
Sending command to a server node will cause that server node to invoke
``KVStoreServer.controller`` to execute the command.
This function returns after the command has been executed in all server
This function returns after the command has been executed on all server
nodes.
Parameters
Expand All @@ -383,7 +377,7 @@ def _send_command_to_servers(self, head, body):
self.handle, mx_uint(head), c_str(body)))

def create(name='local'):
"""Create a new KVStore.
"""Creates a new KVStore.
Parameters
----------
Expand Down

0 comments on commit 4b03a6a

Please sign in to comment.