Manages a service within an octopus by processing certain infotons. More...

#include <tentacle.h>

Inheritance diagram for octopi::tentacle:

[legend]

Collaboration diagram for octopi::tentacle:

Public Types
enum	constants { DEFAULT_RATE = 40 }

enum	outcomes { OKAY = basis::common::OKAY , NOT_FOUND = basis::common::NOT_FOUND , ALREADY_EXISTS = basis::common::EXISTING , BAD_INPUT = basis::common::BAD_INPUT , NO_SPACE = basis::common::NO_SPACE , GARBAGE = basis::common::GARBAGE , DISALLOWED = basis::common::DISALLOWED , NO_HANDLER = basis::common::NO_HANDLER , PARTIAL = basis::common::PARTIAL , ENCRYPTION_MISMATCH = basis::common::ENCRYPTION_MISMATCH }

Public Member Functions
	tentacle (const structures::string_array &group_name, bool backgrounded, int motivational_rate=tentacle::DEFAULT_RATE)
	constructs a tentacle that handles infotons with the "group_name". More...

virtual	~tentacle ()

	DEFINE_CLASS_NAME ("tentacle")

const structures::string_array &	group () const
	returns the name of the group that this tentacle services. More...

bool	backgrounding () const
	reports on whether this tentacle supports background operation or not. More...

int	motivational_rate () const
	returns the background processing rate this was constructed with. More...

virtual basis::outcome	reconstitute (const structures::string_array &classifier, basis::byte_array &packed_form, infoton *&reformed)=0
	regenerates an infoton from its packed form. More...

virtual basis::outcome	consume (infoton &to_chow, const octopus_request_id &item_id, basis::byte_array &transformed)=0
	this is the main function that processes infotons for this tentacle. More...

virtual void	expunge (const octopus_entity &to_remove)=0
	called to remove traces of the entity "to_remove". More...

basis::outcome	enqueue (infoton *to_chow, const octopus_request_id &item_id)
	holds onto infotons coming from the octopus for backgrounding. More...

infoton *	next_request (octopus_request_id &item_id)
	pops out the next queued request for processing. More...

bool	store_product (infoton *product, const octopus_request_id &original_id)
	used by tentacles to store the objects they produce from infotons. More...

void	attach_storage (entity_data_bin &storage)
	used when a tentacle is being integrated with an octopus. More...

void	detach_storage ()
	unhooks the storage bin from this tentacle. More...

entity_data_bin *	get_storage ()
	returns the current pointer, which might be nil. More...

void	propel_arm ()
	invoked by our thread to cause requests to be processed. More...

Static Public Member Functions
static const char *	outcome_name (const basis::outcome &to_name)
	returns the textual form of the outcome "to_name". More...

Detailed Description

Manages a service within an octopus by processing certain infotons.

Definition at line 35 of file tentacle.h.

Member Enumeration Documentation

◆ constants

enum octopi::tentacle::constants

Enumerator
DEFAULT_RATE

Definition at line 49 of file tentacle.h.

◆ outcomes

enum octopi::tentacle::outcomes

Enumerator
OKAY
NOT_FOUND
ALREADY_EXISTS
BAD_INPUT
NO_SPACE
GARBAGE
DISALLOWED
NO_HANDLER	no handler for that type of infoton.
PARTIAL	processing of request is partially done.
ENCRYPTION_MISMATCH	there is a disconnect regarding encryption.

Definition at line 64 of file tentacle.h.

Constructor & Destructor Documentation

◆ tentacle()

tentacle::tentacle	(	const structures::string_array &	group_name,
		bool	backgrounded,
		int	motivational_rate = `tentacle::DEFAULT_RATE`
	)

constructs a tentacle that handles infotons with the "group_name".

if "backgrounded" is true, then the tentacle will periodically look for queued requests at the specified "motivational_rate". if "backgrounded" is false, then the tentacle will not perform any background processing, meaning that it can only provide immediate evaluation for an octopus.

Definition at line 73 of file tentacle.cpp.

References motivational_rate().

◆ ~tentacle()

tentacle::~tentacle ( )

virtual

Definition at line 87 of file tentacle.cpp.

References basis::WHACK().

Member Function Documentation

◆ attach_storage()

void tentacle::attach_storage ( entity_data_bin & storage )

used when a tentacle is being integrated with an octopus.

not for casual external users. note that the tentacle's background processing will not be started until attach is called and that it stops when detach is called.

Definition at line 106 of file tentacle.cpp.

References NULL_POINTER.

Referenced by octopi::octopus::add_tentacle().

◆ backgrounding()

bool octopi::tentacle::backgrounding ( ) const

inline

reports on whether this tentacle supports background operation or not.

Definition at line 58 of file tentacle.h.

Referenced by octopi::octopus::evaluate().

◆ consume()

virtual basis::outcome octopi::tentacle::consume	(	infoton &	to_chow,
		const octopus_request_id &	item_id,
		basis::byte_array &	transformed
	)

pure virtual

this is the main function that processes infotons for this tentacle.

the octopus will feed this function with appropriate data "to_chow" for infotons that are to be processed by this tentacle's group(). the "item_id" provides for the requesting entity an origination marker that can be used in produce() below. the outcome indicates whether the processing was successful. processing could fail due to a missing handler for the item, due to erronous data in the infoton, because of resource limits placed on the tentacle, from explicit rejection by the tentacle, or due to other causes. the "transformed" is a packed infoton that may be generated during the consumption of "to_chow" (it must actually be a packed classifier and then the packed infoton). if it can be unpacked successfully, then it will be treated as the actual infoton that was to be consumed. this is only expected from a filter. note: the infoton "to_chow" can be destructively manipulated by the tentacle, including patching the classifier for internal octopi or rearranging any data contained in "to_chow". none of these changes will be seen by the entity that requested processing. regarding filters: if this tentacle is serving as a filter, then it may be presented with infotons that are not covered by its group. given such an infoton, the tentacle should perform whatever filtering is to be done, including modifying the infoton appropriately, and return PARTIAL when it liked the infoton or DISALLOWED when it rejects the infoton. it is understood that the infoton will be passed along to the rest of the tentacles when the successful result of PARTIAL is returned.

Implemented in synchronic::list_manager, octopi::login_tentacle, octopi::file_transfer_tentacle, octopi::unwrapping_tentacle, octopi::encryption_tentacle, and octopi::identity_tentacle.

Referenced by octopi::octopus::evaluate(), and propel_arm().

◆ DEFINE_CLASS_NAME()

octopi::tentacle::DEFINE_CLASS_NAME ( "tentacle" )

◆ detach_storage()

void tentacle::detach_storage ( )

unhooks the storage bin from this tentacle.

Definition at line 112 of file tentacle.cpp.

References NULL_POINTER.

◆ enqueue()

outcome tentacle::enqueue	(	infoton *	to_chow,
		const octopus_request_id &	item_id
	)

holds onto infotons coming from the octopus for backgrounding.

this will add an infoton "to_chow" into the list of objects to be consumed. at some point after a successful outcome from this, the tentacle will be handed the infoton for processing. NOTE: all responsibility for the infoton "to_chow" is passed to this method; the infoton should not be touched in any way after invocation.

Definition at line 131 of file tentacle.cpp.

References GRAB_CONSUMER_LOCK, octopi::entity_data_bin::max_bytes_per_entity(), NO_SPACE, OKAY, octopi::infoton::packed_size(), and basis::WHACK().

Referenced by octopi::octopus::evaluate().

◆ expunge()

virtual void octopi::tentacle::expunge ( const octopus_entity & to_remove )

pure virtual

called to remove traces of the entity "to_remove".

this is an order from the octopus that all traces of the entity "to_remove" should now be cleaned out. that entity has been utterly destroyed and any data structures held for it should be thrown out also. the required actions are specific to the tentacle's design.

Implemented in octopi::login_tentacle, octopi::file_transfer_tentacle, octopi::encryption_tentacle, and synchronic::list_manager.

◆ get_storage()

entity_data_bin * tentacle::get_storage ( )

returns the current pointer, which might be nil.

Definition at line 104 of file tentacle.cpp.

◆ group()

const string_array & tentacle::group ( ) const

returns the name of the group that this tentacle services.

this can be a single string or it can be a list of names. a tentacle can only service one name group currently.

Definition at line 96 of file tentacle.cpp.

Referenced by octopi::octopus::add_tentacle(), octopi::octopus::evaluate(), and synchronic::list_manager::list_name().

◆ motivational_rate()

int tentacle::motivational_rate ( ) const

returns the background processing rate this was constructed with.

Definition at line 101 of file tentacle.cpp.

Referenced by tentacle().

◆ next_request()

infoton * tentacle::next_request ( octopus_request_id & item_id )

pops out the next queued request for processing.

this function locates the next request for the tentacle when it is in its consume() method. the returned infoton was previously passed to the enqueue() method and needs to be processed. if there are no requests ready, NULL_POINTER is returned.

Definition at line 158 of file tentacle.cpp.

References GRAB_CONSUMER_LOCK, and NULL_POINTER.

Referenced by propel_arm().

◆ outcome_name()

const char * tentacle::outcome_name ( const basis::outcome & to_name )

static

returns the textual form of the outcome "to_name".

Definition at line 98 of file tentacle.cpp.

Referenced by octopi::octopus::evaluate().

◆ propel_arm()

void tentacle::propel_arm ( )

invoked by our thread to cause requests to be processed.

Definition at line 170 of file tentacle.cpp.

References octopi::infoton::classifier(), consume(), FUNCDEF, LOG, next_request(), NULL_POINTER, OKAY, structures::string_array::text_form(), and basis::WHACK().

◆ reconstitute()

virtual basis::outcome octopi::tentacle::reconstitute	(	const structures::string_array &	classifier,
		basis::byte_array &	packed_form,
		infoton *&	reformed
	)

pure virtual

regenerates an infoton from its packed form.

given the "classifier" under which the object is categorized, this reconstructs a "reformed" infoton equivalent to the flattened infoton in "packed_form". the "packed_form" is destructively consumed. NOTE: it is crucial that the derived method calls set_classifier() on the "reformed" infoton from the passed "classifier".

Implemented in synchronic::list_manager, octopi::login_tentacle, octopi::file_transfer_tentacle, octopi::unwrapping_tentacle, octopi::encryption_tentacle, octopi::tentacle_helper< contents >, octopi::tentacle_helper< identity_infoton >, octopi::tentacle_helper< encryption_wrapper >, octopi::tentacle_helper< file_transfer_infoton >, octopi::tentacle_helper< security_infoton >, octopi::tentacle_helper< encryption_infoton >, octopi::tentacle_helper< unhandled_request >, and octopi::identity_tentacle.

Referenced by octopi::octopus::restore().

◆ store_product()

bool tentacle::store_product	(	infoton *	product,
		const octopus_request_id &	original_id
	)

used by tentacles to store the objects they produce from infotons.

this will cache the "product" object and its "original_id" for later retrieval from the entity_data_bin we were given when hooked to an octopus. note that the "product" must be allocated dynamically and that it becomes owned by the response bin after this call (do not delete the original pointer). if the item would not fit in the entity's bin, then false is returned and the "product" is deleted.

Definition at line 118 of file tentacle.cpp.

References octopi::entity_data_bin::add_item(), FUNCDEF, and LOG.

Referenced by octopi::identity_tentacle::consume(), octopi::encryption_tentacle::consume(), and octopi::login_tentacle::consume().

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

/opt/feistymeow.org/feisty_meow/octopi/library/octopus/tentacle.h
/opt/feistymeow.org/feisty_meow/octopi/library/octopus/tentacle.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ constants

◆ outcomes

Constructor & Destructor Documentation

◆ tentacle()

◆ ~tentacle()

Member Function Documentation

◆ attach_storage()

◆ backgrounding()

◆ consume()

◆ DEFINE_CLASS_NAME()

◆ detach_storage()

◆ enqueue()

◆ expunge()

◆ get_storage()

◆ group()

◆ motivational_rate()

◆ next_request()

◆ outcome_name()

◆ propel_arm()

◆ reconstitute()

◆ store_product()