Octopus is a design pattern for generalized request processing systems. More...

#include <octopus.h>

Inheritance diagram for octopi::octopus:

Collaboration diagram for octopi::octopus:

Public Member Functions
	octopus (const basis::astring &name, int max_size_per_entity)
	constructs an octopus named "name". More...

virtual	~octopus ()

	DEFINE_CLASS_NAME ("octopus")

const basis::astring &	name () const
	returns the name that the octopus was constructed with. More...

basis::outcome	add_tentacle (tentacle *to_add, bool filter=false)
	hooks a tentacle in to provide processing of one type of infoton. More...

basis::outcome	remove_tentacle (const structures::string_array &group_name, tentacle *&free_me)
	removes the tentacle listed for the "group_name", if any. More...

basis::outcome	zap_tentacle (const structures::string_array &group_name)
	similar to remove_tentacle(), but destroys the tentacle. More...

octopus_entity	issue_identity ()
	creates an entity identifier that is unique for this octopus. More...

void	expunge (const octopus_entity &to_remove)
	invokes every tentacle's expunge() method on the id "to_remove". More...

entity_data_bin &	responses ()
	allows external access to our set of results. More...

basis::outcome	restore (const structures::string_array &classifier, basis::byte_array &packed_form, infoton *&reformed)
	regenerates a packed infoton given its classifier. More...

basis::outcome	evaluate (infoton *request, const octopus_request_id &item_id, bool now=false)
	tries to process the "request" using the current set of tentacles. More...

infoton *	acquire_result (const octopus_entity &requester, octopus_request_id &original_id)
	acquires responses to previous requests if there are any waiting. More...

infoton *	acquire_specific_result (const octopus_request_id &original_id)
	supports seeking the result for a specific request. More...

tentacle *	lock_tentacle (const structures::string_array &tentacle_name)
	locates the tentacle with the "tentacle_name" and returns it. More...

void	unlock_tentacle (tentacle *to_unlock)
	unlocks the octopus when given a previously locked tentacle. More...

void	lock_tentacles ()
	locks the tentacle list for use with locked_get_tentacle. More...

int	locked_tentacle_count ()
	number of tentacles. More...

tentacle *	locked_get_tentacle (int indy)
	access indy'th tentacle. More...

void	unlock_tentacles ()
	unlocks the list. More...

void	periodic_cleaning ()
	flushes any abandoned data from the response bin. More...

Detailed Description

Octopus is a design pattern for generalized request processing systems.

Octopus is a plug-in module manager that can serve as the base for highly extensible program architectures. Each module is called a tentacle, following the conceit of the naming conventions, and it services one type of request. The requests come in the form of infoton objects, where the tentacle that handles each class of infotons is uniquely identifiable. Note that the outcomes returned here are from the tentacle's set of outcomes.

Definition at line 46 of file octopus.h.

Constructor & Destructor Documentation

◆ octopus()

octopi::octopus::octopus	(	const basis::astring &	name,
		int	max_size_per_entity
	)

constructs an octopus named "name".

the "name" string identifies the arena where this octopus is running. this could be a network host or other identification string. the "max_size_per_entity" is the largest that we allow one entity's bin of pending data to be. this should be quite large if massive transactions need to be processed.

Definition at line 142 of file octopus.cpp.

References add_tentacle().

◆ ~octopus()

octopi::octopus::~octopus ( )

virtual

Definition at line 160 of file octopus.cpp.

References FUNCDEF, and basis::WHACK().

Member Function Documentation

◆ acquire_result()

infoton * octopi::octopus::acquire_result	(	const octopus_entity &	requester,
		octopus_request_id &	original_id
	)

acquires responses to previous requests if there are any waiting.

it returns an infoton for the "requester", if any are available. call this function repeatedly to ensure that all responses have been provided. the "original_id" is a copy of the "item_id" that was originally passed to evaluate_request(). the returned object must eventually be destroyed if non-null.

Definition at line 190 of file octopus.cpp.

References octopi::entity_data_bin::acquire_for_entity().

◆ acquire_specific_result()

infoton * octopi::octopus::acquire_specific_result ( const octopus_request_id & original_id )

supports seeking the result for a specific request.

either the infoton that is a response to "original_id" will be returned or NULL_POINTER.

Definition at line 187 of file octopus.cpp.

References octopi::entity_data_bin::acquire_for_identifier().

Referenced by octopi::recursive_file_copy::copy_hierarchy().

◆ add_tentacle()

outcome octopi::octopus::add_tentacle	(	tentacle *	to_add,
		bool	filter = `false`
	)

hooks a tentacle in to provide processing of one type of infoton.

lists the tentacle "to_add" as being responsible for handling requests for the tentacle's group(). note that the octopus takes over control of the "to_add" pointer; do not destroy that pointer independently, and do not use the tentacle after adding it to the octopus unless the tentacle is thread-safe. the add will replace an existing tentacle if it was already registered under the same group name. if the "filter" flag is enabled, then this tentacle is considered a filter; it will be consulted on all infotons before they are processed. filters will be invoked in the order that they are added.

Definition at line 253 of file octopus.cpp.

References octopi::tentacle::ALREADY_EXISTS, octopi::tentacle::attach_storage(), octopi::tentacle::BAD_INPUT, FUNCDEF, GRAB_LOCK, octopi::tentacle::group(), basis::array< contents >::length(), LOG, octopi::tentacle::OKAY, structures::string_array::text_form(), and zap_tentacle().

Referenced by synchronic::list_synchronizer::add_list(), cromp::cromp_common::add_tentacle(), octopi::recursive_file_copy::copy_hierarchy(), and octopus().

◆ DEFINE_CLASS_NAME()

octopi::octopus::DEFINE_CLASS_NAME ( "octopus" )

◆ evaluate()

outcome octopi::octopus::evaluate	(	infoton *	request,
		const octopus_request_id &	item_id,
		bool	now = `false`
	)

tries to process the "request" using the current set of tentacles.

if there is no group handler for the "request", then NO_HANDLER will be returned. the classifier for "request" specifies the group name for processing. NOTE: the octopus assumes all responsibility for the "request", even if the outcome denotes failure; do not touch the "request" after this call. if the "request" will be processed further by lower level octopi, then the classifier can be patched as appropriate. the "item_id" must be maintained with the request in order to identify the entity making the request and the sequence number of this particular request. the "now" parameter specifies whether the processing must occur immediately; if false, the processing will occur later when the tentacle get around to it. if "now" is true, there is more load on the octopus itself. note that "now" is ignored if the tentacle does not support backgrounding; true is always assumed for that case.

Definition at line 351 of file octopus.cpp.

References octopi::tentacle::backgrounding(), octopi::tentacle::BAD_INPUT, octopi::infoton::classifier(), octopi::tentacle::consume(), octopi::tentacle::enqueue(), octopi::infoton::fast_unpack(), FUNCDEF, GRAB_LOCK, octopi::tentacle::group(), basis::array< contents >::length(), basis::mutex::lock(), LOG, octopi::tentacle::NOT_FOUND, timely::now(), NULL_POINTER, octopi::tentacle::OKAY, octopi::tentacle::outcome_name(), octopi::tentacle::PARTIAL, periodic_cleaning(), structures::string_array::prefix_compare(), restore(), structures::string_array::text_form(), basis::astring::text_form(), basis::mutex::unlock(), basis::WHACK(), and WHACK_RETURN.

Referenced by octopi::recursive_file_copy::copy_hierarchy().

◆ expunge()

void octopi::octopus::expunge ( const octopus_entity & to_remove )

invokes every tentacle's expunge() method on the id "to_remove".

this indicates that the entity is no longer extant and resources held for it can be destroyed.

Definition at line 200 of file octopus.cpp.

References octopi::entity_data_bin::acquire_for_entity(), FUNCDEF, GRAB_LOCK, LOG, octopi::octopus_entity::mangled_form(), octopi::MAXIMUM_TRASH_SIZE, structures::amorph< contents >::reset(), and responses().

◆ issue_identity()

octopus_entity octopi::octopus::issue_identity ( )

creates an entity identifier that is unique for this octopus.

this provides a unique identity using the "name" specified in the constructor and the current process id. the sequence number and random add_in are generated by this class also.

Definition at line 527 of file octopus.cpp.

References mathematics::chaos::inclusive(), MAXINT32, and processes::safe_roller::next_id().

Referenced by octopi::identity_tentacle::consume(), and octopi::recursive_file_copy::copy_hierarchy().

◆ lock_tentacle()

tentacle * octopi::octopus::lock_tentacle ( const structures::string_array & tentacle_name )

locates the tentacle with the "tentacle_name" and returns it.

the octopus will stay locked until the unlock_tentacle() method is invoked.

Definition at line 515 of file octopus.cpp.

References basis::array< contents >::length(), basis::mutex::lock(), NULL_POINTER, and basis::mutex::unlock().

◆ lock_tentacles()

void octopi::octopus::lock_tentacles ( )

locks the tentacle list for use with locked_get_tentacle.

Definition at line 174 of file octopus.cpp.

References basis::mutex::lock().

Referenced by synchronic::list_synchronizer::clean(), and synchronic::list_synchronizer::update().

◆ locked_get_tentacle()

tentacle * octopi::octopus::locked_get_tentacle ( int indy )

access indy'th tentacle.

Definition at line 184 of file octopus.cpp.

Referenced by synchronic::list_synchronizer::clean(), and synchronic::list_synchronizer::update().

◆ locked_tentacle_count()

int octopi::octopus::locked_tentacle_count ( )

number of tentacles.

Definition at line 180 of file octopus.cpp.

Referenced by synchronic::list_synchronizer::clean(), and synchronic::list_synchronizer::update().

◆ name()

const astring & octopi::octopus::name ( ) const

returns the name that the octopus was constructed with.

Definition at line 182 of file octopus.cpp.

◆ periodic_cleaning()

void octopi::octopus::periodic_cleaning ( )

flushes any abandoned data from the response bin.

Definition at line 498 of file octopus.cpp.

References octopi::entity_data_bin::clean_out_deadwood(), FUNCDEF, octopi::OCTOPUS_CHECKING_INTERVAL, and timely::time_stamp::reset().

Referenced by evaluate(), and restore().

◆ remove_tentacle()

outcome octopi::octopus::remove_tentacle	(	const structures::string_array &	group_name,
		tentacle *&	free_me
	)

removes the tentacle listed for the "group_name", if any.

"free_me" provides the means for getting back what was originally registered. NOTE: remember to destroy "free_me" if that's appropriate (i.e. it was dynamically allocated, has no other users and no other entity has responsibility for it).

Definition at line 279 of file octopus.cpp.

References octopi::tentacle::BAD_INPUT, continuable_error, FUNCDEF, basis::array< contents >::length(), basis::mutex::lock(), basis::negative(), octopi::tentacle::NOT_FOUND, NULL_POINTER, octopi::tentacle::OKAY, basis::mutex::unlock(), and basis::WHACK().

Referenced by zap_tentacle().

◆ responses()

entity_data_bin & octopi::octopus::responses ( )

allows external access to our set of results.

this should not be used unless you know what you're doing.

Definition at line 178 of file octopus.cpp.

Referenced by octopi::recursive_file_copy::copy_hierarchy(), expunge(), cromp::cromp_server::get_sizes(), cromp::cromp_common::max_bytes_per_entity(), and cromp::cromp_server::responses_text_form().

◆ restore()

outcome octopi::octopus::restore	(	const structures::string_array &	classifier,
		basis::byte_array &	packed_form,
		infoton *&	reformed
	)

regenerates a packed infoton given its classifier.

locates the appropriate type of infoton with the "classifier" and consumes the bytes in "packed_form" to return a new version of the original data in "reformed", if possible.

Definition at line 318 of file octopus.cpp.

References octopi::tentacle::BAD_INPUT, FUNCDEF, GRAB_LOCK, basis::array< contents >::length(), LOG, octopi::tentacle::NOT_FOUND, NULL_POINTER, periodic_cleaning(), octopi::tentacle::reconstitute(), and structures::string_array::text_form().

Referenced by cromp::cromp_client::decrypt_package_as_needed(), and evaluate().

◆ unlock_tentacle()

void octopi::octopus::unlock_tentacle ( tentacle * to_unlock )

unlocks the octopus when given a previously locked tentacle.

this must be the same object that was obtained via the lock_tentacle() method.

Definition at line 194 of file octopus.cpp.

References NULL_POINTER, and basis::mutex::unlock().

◆ unlock_tentacles()

void octopi::octopus::unlock_tentacles ( )

unlocks the list.

Definition at line 176 of file octopus.cpp.

References basis::mutex::unlock().

Referenced by synchronic::list_synchronizer::clean(), and synchronic::list_synchronizer::update().

◆ zap_tentacle()

outcome octopi::octopus::zap_tentacle ( const structures::string_array & group_name )

similar to remove_tentacle(), but destroys the tentacle.

Definition at line 245 of file octopus.cpp.

References NULL_POINTER, remove_tentacle(), and basis::WHACK().

Referenced by add_tentacle(), and synchronic::list_synchronizer::zap_list().

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

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ octopus()

◆ ~octopus()

Member Function Documentation

◆ acquire_result()

◆ acquire_specific_result()

◆ add_tentacle()

◆ DEFINE_CLASS_NAME()

◆ evaluate()

◆ expunge()

◆ issue_identity()

◆ lock_tentacle()

◆ lock_tentacles()

◆ locked_get_tentacle()

◆ locked_tentacle_count()

◆ name()

◆ periodic_cleaning()

◆ remove_tentacle()

◆ responses()

◆ restore()

◆ unlock_tentacle()

◆ unlock_tentacles()

◆ zap_tentacle()