syft.generic.pointers.object_pointer

Module Contents

class syft.generic.pointers.object_pointer.ObjectPointer(location: BaseWorker = None, id_at_location: Union[str, int] = None, owner: BaseWorker = None, id: Union[str, int] = None, garbage_collect_data: bool = True, point_to_attr: str = None, tags: List[str] = None, description: str = None)

Bases: syft.generic.object.AbstractObject

A pointer to a remote object.

An ObjectPointer forwards all API calls to the remote. ObjectPointer objects point to objects. They exist to mimic the entire API of an object, but instead of computing a function locally (such as addition, subtraction, etc.) they forward the computation to a remote machine as specified by self.location. Specifically, every ObjectPointer has a object located somewhere that it points to (they should never exist by themselves). The objects being pointed to can be on the same machine or (more commonly) on a different one. Note further that a ObjectPointer does not know the nature how it sends messages to the object it points to (whether over socket, http, or some other protocol) as that functionality is abstracted in the BaseWorker object in self.location.

static create_pointer(obj, location: AbstractWorker = None, id_at_location: str or int = None, register: bool = False, owner: AbstractWorker = None, ptr_id: str or int = None, garbage_collect_data=None)

Creates a pointer to the “self” FrameworkTensor object.

This method is called on a FrameworkTensor object, returning a pointer to that object. This method is the CORRECT way to create a pointer, and the parameters of this method give all possible attributes that a pointer can be created with.

Parameters

  • location – The AbstractWorker object which points to the worker on which this pointer’s object can be found. In nearly all cases, this is self.owner and so this attribute can usually be left blank. Very rarely you may know that you are about to move the Tensor to another worker so you can pre-initialize the location attribute of the pointer to some other worker, but this is a rare exception.

  • id_at_location – A string or integer id of the tensor being pointed to. Similar to location, this parameter is almost always self.id and so you can leave this parameter to None. The only exception is if you happen to know that the ID is going to be something different than self.id, but again this is very rare and most of the time, setting this means that you are probably doing something you shouldn’t.

  • register – A boolean parameter (default False) that determines whether to register the new pointer that gets created. This is set to false by default because most of the time a pointer is initialized in this way so that it can be sent to someone else (i.e., “Oh you need to point to my tensor? let me create a pointer and send it to you” ). Thus, when a pointer gets created, we want to skip being registered on the local worker because the pointer is about to be sent elsewhere. However, if you are initializing a pointer you intend to keep, then it is probably a good idea to register it, especially if there is any chance that someone else will initialize a pointer to your pointer.

  • owner – A AbstractWorker parameter to specify the worker on which the pointer is located. It is also where the pointer is registered if register is set to True.

  • ptr_id – A string or integer parameter to specify the id of the pointer in case you wish to set it manually for any special reason. Otherwise, it will be set randomly.

  • garbage_collect_data – If true (default), delete the remote tensor when the pointer is deleted.

  • local_autograd – Use autograd system on the local machine instead of PyTorch’s autograd on the workers.

  • preinitialize_grad – Initialize gradient for AutogradTensors to a tensor.

Returns

A FrameworkTensor[ObjectPointer] pointer to self. Note that this object itself will likely be wrapped by a FrameworkTensor wrapper.

wrap(self, register=True, type=None, **kwargs)

Wraps the class inside framework tensor.

Because PyTorch/TF do not (yet) support functionality for creating arbitrary Tensor types (via subclassing torch.Tensor), in order for our new tensor types (such as PointerTensor) to be usable by the rest of PyTorch/TF (such as PyTorch’s layers and loss functions), we need to wrap all of our new tensor types inside of a native PyTorch type.

This function adds a .wrap() function to all of our tensor types (by adding it to AbstractTensor), such that (on any custom tensor my_tensor), my_tensor.wrap() will return a tensor that is compatible with the rest of the PyTorch/TensorFlow API.

Returns

A wrapper tensor of class type, or whatever is specified as default by the current syft.framework.Tensor.

classmethod handle_func_command(cls, command)

Receive an instruction for a function to be applied on a Pointer, Get the remote location to send the command, send it and get a pointer to the response, return. :param command: instruction of a function command: (command name, None, arguments[, kwargs]) :return: the response of the function command

classmethod find_a_pointer(cls, command)

Find and return the first pointer in the args object, using a trick with the raising error RemoteObjectFoundError

get(self, user=None, reason: str = '', deregister_ptr: bool = True)

Requests the object being pointed to.

The object to which the pointer points will be requested, serialized and returned.

Note

This will typically mean that the remote object will be removed/destroyed.

Parameters

  • user (obj, optional) – authenticate/allow user to perform get on remote private objects.

  • reason (str, optional) – a description of why the data scientist wants to see it.

  • deregister_ptr (bool, optional) – this determines whether to deregister this pointer from the pointer’s owner during this method. This defaults to True because the main reason people use this method is to move the tensor from the location to the local one, at which time the pointer has no use.

Returns

An AbstractObject object which is the tensor (or chain) that this object used to point to on a location.

TODO: add param get_copy which doesn’t destroy remote if true.

__str__(self)

Returns a string version of this pointer.

This is primarily for end users to quickly see things about the object. This tostring shouldn’t be used for anything else though as it’s likely to change. (aka, don’t try to parse it to extract information. Read the attribute you need directly). Also, don’t use this to-string as a serialized form of the pointer.

__repr__(self)

Returns the to-string method.

When called using __repr__, most commonly seen when returned as cells in Jupyter notebooks.

__del__(self)

This method garbage collects the object this pointer is pointing to. By default, PySyft assumes that every object only has one pointer to it. Thus, if the pointer gets garbage collected, we want to automatically garbage collect the object being pointed to.

_create_attr_name_string(self, attr_name)
attr(self, attr_name)
setattr(self, name, value)
static simplify(worker: AbstractWorker, ptr: ObjectPointer)

This function takes the attributes of a ObjectPointer and saves them in a dictionary :param ptr: a ObjectPointer :type ptr: ObjectPointer

Returns

a tuple holding the unique attributes of the pointer

Return type

tuple

Examples

data = simplify(ptr)

static detail(worker: AbstractWorker, object_tuple: tuple)

This function reconstructs an ObjectPointer given it’s attributes in form of a dictionary. We use the spread operator to pass the dict data as arguments to the init method of ObjectPointer :param worker: the worker doing the deserialization :param tensor_tuple: a tuple holding the attributes of the ObjectPointer

Returns

an ObjectPointer

Return type

ObjectPointer

Examples

ptr = detail(data)