The base class for all requests between nodes. More...

#include <VFS_node.h>

Inheritance diagram for VFS_request:

Public Types
enum	requestType { none = 0 , ls , create , rm , read , write , metadata , diff , submit , subscribe , unsubscribe , acl , report , requestlock , releaselock , code , codeDirectory }
	Requests perform one of these actions. More...

Public Member Functions
	VFS_request (const VFS_request &c)
	Copy constructor. More...

	VFS_request (requestType type=VFS_request::none, VFS_node *origin=nullptr, QString path="", QString user="unknown", QJsonDocument data=QJsonDocument(), QJsonObject metadata=QJsonObject(), bool dontDelete=false)
	VFS_request constructor. More...

virtual	~VFS_request ()
	VFS_request destructor. More...

virtual void	copyCallback (VFS_request *d)
	Copy the data from a callback to this VFS_request. More...

virtual VFS_request *	createDiff (VFS_node *origin, QString originPath)
	VFS_request::createDiff. More...

virtual void	fromJsonObject (QJsonObject json, bool includeInitialPath=false)
	Deserialize a JSON string into a VFS_request. More...

virtual VFS_request *	getCallback (VFS_node *receiver)
	Create and chain a VFS_request for a receiver. More...

bool	hasCallback ()
	Check if this request has a callback set. More...

virtual void	setCallback (VFS_request *c)
	Chain a callback onto this request. More...

virtual void	timerEvent (QTimerEvent *e=nullptr)
	The callback for when a request times out. More...

virtual QByteArray	toJson (postID id=0, bool ignoreSuccess=false, bool includeInitialPath=false)
	Serialize this request. More...

Static Public Member Functions
static quint32	getSample ()
	Get the current sample count and clear the counter. More...

Public Attributes
VFS_request *	_callback
	request to execute once this request completes More...

QJsonDocument	_data
	the request payload More...

bool	_dontDelete
	A rarely used flag that will cause VFS_node::receiveResponse to not delete the node, which forces the developer to manually delete it when appropriate. More...

QString	_initialPath
	the target path when the request was made (relative to the responder) More...

bool	_isCallback
	whether or not to issue a response (IE, another request is chained to this request, whose response will trigger this one to respond) More...

QJsonObject	_metadata
	the request payload More...

QList< notifyException >	_notifyExceptions
	a list of nodes not to send responses to for this transaction. For instance if a node submits to a node it is subscribed to, it doesn't expect to get the submit data back to itself. More...

VFS_node *	_origin
	the origin of the request More...

QString	_originPath
	the subpath of the origin node More...

QString	_path
	the target path remnant... the remaining path element once the request has found its target More...

QStringList	_prefixPath
	the prefix elements found while searching for the target More...

QByteArray	_rawData
	the request payload, but raw data More...

QString	_reason
	if something (probably bad) happened, this is the reason More...

requestType	_requestType
	the action this request is performing or requesting More...

VFS_node *	_responder
	the receiver of the request More...

VFS_session *	_session
	The session associated with this request. This is an optional value, and care should be taken to check for null as needed. More...

bool	_success
	if the request was successfully completed More...

QString	_user
	who initiated this request, mostly for logging More...

Static Public Attributes
static long	_refcount = 0
	A reference counter for VFS_request instances, used for debugging to ensure all instances are properly deleted. More...

static quint32	_sampleCount = 0
	A count of the number of VFS_requests since the last sample was taken. More...

static QMutex	_sampleLock
	A mutex to protect thread safety of samples. More...

static const char *	requestTypeStrings []
	A printable string for each request type. More...

Protected Member Functions
virtual void	execute ()
	after a request has completed, a request may have a special execute function. More...

Friends
class	VFS_node

Detailed Description

The base class for all requests between nodes.

All data is copied (rather than referenced via pointer) in order to preserve thread safety.

Generally requests are not directly made via the constructor, but instead via VFS_node::createRequest(). Some nodes want special types of requests to be issued.

Definition at line 53 of file VFS_node.h.

Member Enumeration Documentation

◆ requestType

enum VFS_request::requestType

Requests perform one of these actions.

Enumerator
none
ls	list children of a node (1)
create	create a new file/path (2)
rm	delete an existing file/path (3)
read	read full contents (4)
write	write full contents (5)
metadata	read metadata (6)
diff	send a diff (7)
submit	apply a diff (8)
subscribe	subscribe to a path (9)
unsubscribe	unsubscribe from a path (10)
acl	return the ACL defaults for this node (11)
report	provide node report, for debugging (12)
requestlock	request a lock (13)
releaselock	release a lock (14)
code	request code from a node (15)
codeDirectory	request a listing of code served by a node (16)

Definition at line 62 of file VFS_node.h.

Constructor & Destructor Documentation

◆ VFS_request() [1/2]

VFS_request::VFS_request	(	requestType	type = `VFS_request::none`,
		VFS_node *	origin = `nullptr`,
		QString	path = `""`,
		QString	user = `"unknown"`,
		QJsonDocument	data = `QJsonDocument()`,
		QJsonObject	metadata = `QJsonObject()`,
		bool	dontDelete = `false`
	)

VFS_request constructor.

Parameters

type	The request type. This is the action being performed
origin	The node originating the request
path	The path to be searched
user	The user performing the request. In the case of internal operations, this is frequently VFS_node::className()
data	The data payload
metadata	The metadata
dontDelete	A flag indicating whether the request is to be deleted when complete

By default, a _metadata["stamp"] field will be created that contains milliseconds since the epoch. In the future this may be used to sort out conflicting requests, but is currently unused.

The dontDelete flag should be rarely used, and only in cases where an inline VFS_request is being made on the same thread and the result is needed for later operations. Use at your own risk!

This function also increments the VFS_request::_refcount.

Definition at line 74 of file VFS_node.cpp.

◆ VFS_request() [2/2]

VFS_request::VFS_request ( const VFS_request & c )

Copy constructor.

Parameters

c	The VFS_request to copy

This is here only to increment _refcount. Otherwise, it replicates the default copy constructor.

Ideally, with this in place, the VFS_request::_refcount should always return to 0 after all events are processed.

Definition at line 145 of file VFS_node.cpp.

◆ ~VFS_request()

VFS_request::~VFS_request ( )

virtual

VFS_request destructor.

The destructor decrements the VFS_request::_refcount.

If a _callback is set, it will also be deleted.

Definition at line 187 of file VFS_node.cpp.

Member Function Documentation

◆ copyCallback()

void VFS_request::copyCallback ( VFS_request * d )

virtual

Copy the data from a callback to this VFS_request.

Parameters

d	The VFS_request callback

Copy _metadata, _data, _success, and _reason from the callback. These are the payload fields.

Does not modify the _origin, _originPath, _responder, _initialPath, _prefixPath, _path, _callBack, or _user. Those fields are left alone because they indicate the original intent of the request.

Definition at line 355 of file VFS_node.cpp.

◆ createDiff()

VFS_request * VFS_request::createDiff	(	VFS_node *	origin,
		QString	originPath
	)

virtual

VFS_request::createDiff.

Parameters

origin	The origin request of the diff
originPath	The originPath, which is from the subscribers list

Returns: A new VFS_request::diff node, which can be distributed to subscribers

This is called by VFS_node::notifySubscribers(), and is pulled out as a method to allow subclassing, specifically to allow for subclasses of VFS_request to be returned.

See also: VFS_tcp_export_request::createDiff()

Reimplemented in VFS_tcp_export_request.

Definition at line 391 of file VFS_node.cpp.

◆ execute()

void VFS_request::execute ( )

protectedvirtual

after a request has completed, a request may have a special execute function.

This is mainly for subclasses, as the base class only checks for success and issues a warning if _success==false.

Note: If _metadata contains a 'suppressError=true' flag, an unsuccessful error will not be logged. There are cases where a test is being performed and a failure is expected, which should not be logged.

Reimplemented in VFS_httpd_browser_request, VFS_tcp_export_request, and VFS_remotoserver_request.

Definition at line 255 of file VFS_node.cpp.

◆ fromJsonObject()

void VFS_request::fromJsonObject	(	QJsonObject	json,
		bool	includeInitialPath = `false`
	)

virtual

Deserialize a JSON string into a VFS_request.

Parameters

json	The serialized data
includeInitialPath	Override for initial path, which is usually unneeded.

This will unserialize a JSON string and copy values onto this VFS_request object. Useful when data is received from a network.

This will set _requestType, _path, _user, _success, _reason, _initialPath, _data, and _metadata.

Reimplemented in VFS_tcp_export_request.

Definition at line 466 of file VFS_node.cpp.

◆ getCallback()

VFS_request * VFS_request::getCallback ( VFS_node * receiver )

virtual

Create and chain a VFS_request for a receiver.

Parameters

receiver The receiver of the chained VFS_request

Returns: The new request

Chain this VFS_request onto a new one.

For asynchronous requests that need to cross a thread or network boundary, a new request is needed. A new request is not fulfilled until it is completed. This is a very important detail. One cannot query a node for information synchronously in a function unless it is on the same thread. The Qt signal/slot system will execute immediately when working on a single thread in an inline function, however best practice is to never assume that a request will be performed on the current working thread.

Of course, rules were made to be broken, and you have to think about what you're trying to do. Use wisely!

This will create a new VFS_request by copying _data, _metadata, and _notifyExceptions. After the callback is created, any part of the request can be modified. Usually the developer will need to tweak the path or metadata of this new object.

Definition at line 316 of file VFS_node.cpp.

◆ getSample()

quint32 VFS_request::getSample ( )

static

Get the current sample count and clear the counter.

Returns: The _sampleCount value

Definition at line 235 of file VFS_node.cpp.

◆ hasCallback()

bool VFS_request::hasCallback ( )

Check if this request has a callback set.

Returns: boolean if _callback is set

Definition at line 336 of file VFS_node.cpp.

◆ setCallback()

void VFS_request::setCallback ( VFS_request * c )

virtual

Chain a callback onto this request.

Parameters

c	The VFS_request object

The callback will be executed in the VFS_node::receiveResponse() function after the initial request is completed.

Multiple requests and callbacks can be chained together. It would be a very special case where this function is called, as it exists only to clear the semantics of creating request chains, and is called by VFS_request::getCallback().

Generally one will just want to call VFS_request::getCallback(), because a request needs to know what to report back to, which is what this function sets, however it makes more spoken language sense to "get a callback" than to "set a callback", given the direction of flow.

See also: Requests

Definition at line 286 of file VFS_node.cpp.

◆ timerEvent()

void VFS_request::timerEvent ( QTimerEvent * e = nullptr )

virtual

The callback for when a request times out.

This can be enabled as a debug output by defining (or uncommenting) the DEBUG_DANGLING_REQUESTS define call in VFS_node.h.

By enabling this, VFS_requests become a QObject and can trigger the timerEvent.

The timerEvent only warns the developer that a request hasn't been serviced during the last 10 seconds. This means that the request was not properly disposed of, or the request queue is too long to be serviced in a reasonable amount of time.

If the request was satisfied but not deleted, this indicates that your code is missing a delete command somewhere after the request has been serviced.

If the request times out before being serviced, it may indicate that you need to refactor your code to handle the quantity of volume being supplied.

Definition at line 220 of file VFS_node.cpp.

◆ toJson()

QByteArray VFS_request::toJson	(	postID	id = `0`,
		bool	ignoreSuccess = `false`,
		bool	includeInitialPath = `false`
	)

virtual

Serialize this request.

Parameters

id	A request id, used to match requests coming back from a network request
ignoreSuccess	Usually we only want _data if there is _success. Override that here.
includeInitialPath	The initial path is usually useless on a receiving side, as that context doesn't match this context.

Returns: The JSON-serialized VFS_request

This is the mechanism used to send data over a network, for instance. It can also be useful for debugging.

Only _requestType, _path, _user, _metadata, _data, _reason, and _success are serialized.

Reimplemented in VFS_tcp_export_request.

Definition at line 415 of file VFS_node.cpp.

Friends And Related Function Documentation

◆ VFS_node

friend class VFS_node

friend

Definition at line 56 of file VFS_node.h.

Member Data Documentation

◆ _callback

VFS_request* VFS_request::_callback

request to execute once this request completes

Definition at line 97 of file VFS_node.h.

◆ _data

QJsonDocument VFS_request::_data

the request payload

Definition at line 102 of file VFS_node.h.

◆ _dontDelete

bool VFS_request::_dontDelete

A rarely used flag that will cause VFS_node::receiveResponse to not delete the node, which forces the developer to manually delete it when appropriate.

Definition at line 112 of file VFS_node.h.

◆ _initialPath

QString VFS_request::_initialPath

the target path when the request was made (relative to the responder)

Definition at line 93 of file VFS_node.h.

◆ _isCallback

bool VFS_request::_isCallback

whether or not to issue a response (IE, another request is chained to this request, whose response will trigger this one to respond)

Definition at line 98 of file VFS_node.h.

◆ _metadata

QJsonObject VFS_request::_metadata

the request payload

Definition at line 101 of file VFS_node.h.

◆ _notifyExceptions

QList<notifyException> VFS_request::_notifyExceptions

a list of nodes not to send responses to for this transaction. For instance if a node submits to a node it is subscribed to, it doesn't expect to get the submit data back to itself.

Definition at line 110 of file VFS_node.h.

◆ _origin

VFS_node* VFS_request::_origin

the origin of the request

Definition at line 89 of file VFS_node.h.

◆ _originPath

QString VFS_request::_originPath

the subpath of the origin node

Definition at line 90 of file VFS_node.h.

◆ _path

QString VFS_request::_path

the target path remnant... the remaining path element once the request has found its target

Definition at line 95 of file VFS_node.h.

◆ _prefixPath

QStringList VFS_request::_prefixPath

the prefix elements found while searching for the target

Definition at line 94 of file VFS_node.h.

◆ _rawData

QByteArray VFS_request::_rawData

the request payload, but raw data

Definition at line 103 of file VFS_node.h.

◆ _reason

QString VFS_request::_reason

if something (probably bad) happened, this is the reason

Definition at line 108 of file VFS_node.h.

◆ _refcount

long VFS_request::_refcount = 0

static

A reference counter for VFS_request instances, used for debugging to ensure all instances are properly deleted.

Definition at line 122 of file VFS_node.h.

◆ _requestType

requestType VFS_request::_requestType

the action this request is performing or requesting

Definition at line 87 of file VFS_node.h.

◆ _responder

VFS_node* VFS_request::_responder

the receiver of the request

Definition at line 92 of file VFS_node.h.

◆ _sampleCount

quint32 VFS_request::_sampleCount = 0

static

A count of the number of VFS_requests since the last sample was taken.

Definition at line 123 of file VFS_node.h.

◆ _sampleLock

QMutex VFS_request::_sampleLock

static

A mutex to protect thread safety of samples.

Definition at line 124 of file VFS_node.h.

◆ _session

VFS_session* VFS_request::_session

The session associated with this request. This is an optional value, and care should be taken to check for null as needed.

Definition at line 105 of file VFS_node.h.

◆ _success

bool VFS_request::_success

if the request was successfully completed

Definition at line 107 of file VFS_node.h.

◆ _user

QString VFS_request::_user

who initiated this request, mostly for logging

Definition at line 106 of file VFS_node.h.

◆ requestTypeStrings

const char * VFS_request::requestTypeStrings

static

Initial value:

=
{
        "none",
        "ls",
        "create",
        "rm",
        "read",
        "write",
        "metadata",
        "diff",
        "submit",
        "subscribe",
        "unsubscribe",
        "acl",
        "report",
        "requestlock",
        "releaselock",
        "code",
        "codeDirectory",
        nullptr
}

A printable string for each request type.

Definition at line 127 of file VFS_node.h.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ requestType

Constructor & Destructor Documentation

◆ VFS_request() [1/2]

◆ VFS_request() [2/2]

◆ ~VFS_request()

Member Function Documentation

◆ copyCallback()

◆ createDiff()

◆ execute()

◆ fromJsonObject()

◆ getCallback()

◆ getSample()

◆ hasCallback()

◆ setCallback()

◆ timerEvent()

◆ toJson()

Friends And Related Function Documentation

◆ VFS_node

Member Data Documentation

◆ _callback

◆ _data

◆ _dontDelete

◆ _initialPath

◆ _isCallback

◆ _metadata

◆ _notifyExceptions

◆ _origin

◆ _originPath

◆ _path

◆ _prefixPath

◆ _rawData

◆ _reason

◆ _refcount

◆ _requestType

◆ _responder

◆ _sampleCount

◆ _sampleLock

◆ _session

◆ _success

◆ _user

◆ requestTypeStrings