Main Page Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

TAO_Transport Class Reference

Generic definitions for the Transport class. More...

#include <Transport.h>

Inheritance diagram for TAO_Transport:

[legend]Collaboration diagram for TAO_Transport:

[legend]List of all members.

Public Types
enum	{ TAO_ONEWAY_REQUEST = 0, TAO_TWOWAY_REQUEST = 1, TAO_REPLY }
Public Methods
	TAO_Transport (CORBA::ULong tag, TAO_ORB_Core *orb_core)
	default creator, requres the tag value be supplied. More...
virtual	~TAO_Transport (void)
	destructor. More...
CORBA::ULong	tag (void) const
	The OMG assigns unique tags (a 32-bit unsigned number) to each protocol. More...
TAO_ORB_Core *	orb_core (void) const
	Access the ORB that owns this connection. More...
TAO_Transport_Mux_Strategy *	tms (void) const
	The role of the TAO_Transport_Mux_Strategy is described in more detail in that class' documentation. More...
TAO_Wait_Strategy *	wait_strategy (void) const
	The role of the TAO_Wait_Strategy is described in more detail in that class' documentation. More...
int	handle_output (void)
	Callback method to reactively drain the outgoing data queue. More...
int	bidirectional_flag (void) const
	Get/Set the bidirectional flag. More...
void	bidirectional_flag (int flag)
void	cache_map_entry (TAO_Transport_Cache_Manager::HASH_MAP_ENTRY *entry)
	Set/Get the Cache Map entry. More...
TAO_Transport_Cache_Manager::HASH_MAP_ENTRY *	cache_map_entry (void)
int	id (void) const
	If not set, this will return an integer representation of the `this` pointer for the instance on which it's called. More...
void	id (int id)
unsigned long	purging_order (void) const
	Get and Set the purging order. The purging strategy uses the set version to set the purging order. More...
void	purging_order (unsigned long value)
int	queue_is_empty (void)
void	provide_handle (ACE_Handle_Set &reactor_registered, TAO_EventHandlerSet &unregistered)
	Called by the cache when the cache is closing in order to fill in a handle_set in a thread-safe manner. More...
int	register_handler (void)
	Register the handler with the reactor. More...
ssize_t	send (iovec iov, int iovcnt, size_t &bytes_transferred, const ACE_Time_Value timeout=0)
	This method serializes on handler_lock_, guaranteeing that only thread can execute it on the same instance concurrently. More...
ssize_t	recv (char buffer, size_t len, const ACE_Time_Value timeout=0)
	This method serializes on handler_lock_, guaranteeing that only thread can execute it on the same instance concurrently. More...
virtual int	messaging_init (CORBA::Octet major, CORBA::Octet minor)=0
	Initialising the messaging object. More...
virtual int	tear_listen_point_list (TAO_InputCDR &cdr)
	Extracts the list of listen points from the <cdr> stream. The list would have the protocol specific details of the ListenPoints. More...
int	generate_locate_request (TAO_Target_Specification &spec, TAO_Operation_Details &opdetails, TAO_OutputCDR &output)
	This is a request for the transport object to write a LocateRequest header before it is sent out. More...
virtual int	generate_request_header (TAO_Operation_Details &opd, TAO_Target_Specification &spec, TAO_OutputCDR &msg)
	This is a request for the transport object to write a request header before it sends out the request. More...
int	recache_transport (TAO_Transport_Descriptor_Interface *desc)
	recache ourselves in the cache. More...
virtual void	connection_handler_closing (void)
	Method for the connection handler to signify that it is being closed and destroyed. More...
virtual int	handle_input_i (TAO_Resume_Handle &rh, ACE_Time_Value *max_wait_time=0, int block=0)
	The ACE_Event_Handler adapter invokes this method as part of its handle_input() operation. More...
virtual int	send_request (TAO_Stub stub, TAO_ORB_Core orb_core, TAO_OutputCDR &stream, int message_semantics, ACE_Time_Value *max_time_wait)=0
	Preparing the ORB to receive the reply only once the request is completely sent opens the system to some subtle race conditions: suppose the ORB is running in a multi-threaded configuration, thread A makes a request while thread B is using the Reactor to process all incoming requests. More...
virtual int	send_message (TAO_OutputCDR &stream, TAO_Stub stub=0, int message_semantics=TAO_Transport::TAO_TWOWAY_REQUEST, ACE_Time_Value max_time_wait=0)=0
	Once the ORB is prepared to receive a reply (see send_request() above), and all the arguments have been marshaled the CDR stream must be 'formatted', i.e. More...
virtual int	send_message_shared (TAO_Stub stub, int message_semantics, const ACE_Message_Block message_block, ACE_Time_Value *max_wait_time)
int	send_message_block_chain (const ACE_Message_Block message_block, size_t &bytes_transferred, ACE_Time_Value max_wait_time=0)
	Send a message block chain,. More...
int	send_message_block_chain_i (const ACE_Message_Block message_block, size_t &bytes_transferred, ACE_Time_Value max_wait_time)
	Send a message block chain, assuming the lock is held. More...
void	purge_entry (void)
	Cache management. More...
int	make_idle (void)
	Cache management. More...
int	handle_timeout (const ACE_Time_Value &current_time, const void *act)
Control connection lifecycle
These methods are routed through the TMS object. The TMS strategies implement them correctly.
virtual int	idle_after_send (void)
	Request has been just sent, but the reply is not received. Idle the transport now. More...
virtual int	idle_after_reply (void)
	Request is sent and the reply is received. Idle the transport now. More...
virtual void	close_connection (void)
	Call the implementation method after obtaining the lock. More...
Static Public Methods
TAO_Transport *	_duplicate (TAO_Transport *transport)
void	release (TAO_Transport *transport)
Protected Methods
virtual ACE_Event_Handler *	event_handler_i (void)=0
	Normally a concrete TAO_Transport object has-a ACE_Event_Handler member that function as an adapter between the ACE_Reactor framework and the TAO pluggable protocol framework. More...
virtual TAO_Connection_Handler *	connection_handler_i (void)=0
virtual ACE_Event_Handler *	invalidate_event_handler_i (void)=0
	Typically, this just sets the pointer to the associated connection handler to zero, although it could also clear out any additional resources associated with the handler association. More...
virtual TAO_Pluggable_Messaging *	messaging_object (void)=0
	Return the messaging object that is used to format the data that needs to be sent. More...
virtual ssize_t	send_i (iovec iov, int iovcnt, size_t &bytes_transferred, const ACE_Time_Value timeout=0)=0
	Often the implementation simply forwards the arguments to the underlying ACE_Svc_Handler class. More...
virtual ssize_t	recv_i (char buffer, size_t len, const ACE_Time_Value timeout=0)=0
virtual int	register_handler_i (void)=0
	This method is used by the Wait_On_Reactor strategy. More...
int	parse_consolidate_messages (ACE_Message_Block &bl, TAO_Resume_Handle &rh, ACE_Time_Value *time=0)
	Called by the handle_input_i (). This method is used to parse message read by the handle_input_i () call. It also decides whether the message needs consolidation before processing. More...
int	parse_incoming_messages (ACE_Message_Block &message_block)
	Method does parsing of the message if we have a fresh message in the <message_block> or just returns if we have read part of the previously stored message. More...
size_t	missing_data (ACE_Message_Block &message_block)
	Return if we have any missing data in the queue of messages or determine if we have more information left out in the presently read message to make it complete. More...
virtual int	consolidate_message (ACE_Message_Block &incoming, ssize_t missing_data, TAO_Resume_Handle &rh, ACE_Time_Value *max_wait_time)
	Consolidate the currently read message or consolidate the last message in the queue. The consolidation of the last message in the queue is done by calling consolidate_message_queue (). More...
int	consolidate_fragments (TAO_Queued_Data *qd, TAO_Resume_Handle &rh)
	Bala: Docu??? More...
int	consolidate_message_queue (ACE_Message_Block &incoming, ssize_t missing_data, TAO_Resume_Handle &rh, ACE_Time_Value *max_wait_time)
	First consolidate the message queue. If the message is still not complete, try to read from the handle again to make it complete. If these dont help put the message back in the queue and try to check the queue if we have message to process. (the thread needs to do some work anyway :-)). More...
int	consolidate_extra_messages (ACE_Message_Block &incoming, TAO_Resume_Handle &rh)
	Called by parse_consolidate_message () if we have more messages in one read. Queue up the messages and try to process one of them, atleast at the head of them. More...
int	process_parsed_messages (TAO_Queued_Data *qd, TAO_Resume_Handle &rh)
	Process the message by sending it to the higher layers of the ORB. More...
TAO_Queued_Data *	make_queued_data (ACE_Message_Block &incoming)
	Make a queued data from the <incoming> message block. More...
int	send_message_shared_i (TAO_Stub stub, int message_semantics, const ACE_Message_Block message_block, ACE_Time_Value *max_wait_time)
	Implement send_message_shared() assuming the handler_lock_ is held. More...
int	check_event_handler_i (const char *caller)
Protected Attributes
CORBA::ULong	tag_
	IOP protocol tag. More...
TAO_ORB_Core *	orb_core_
	Global orbcore resource. More...
TAO_Transport_Cache_Manager::HASH_MAP_ENTRY *	cache_map_entry_
	Our entry in the cache. We dont own this. It is here for our convinience. We cannot just change things around. More...
TAO_Transport_Mux_Strategy *	tms_
	Strategy to decide whether multiple requests can be sent over the same connection or the connection is exclusive for a request. More...
TAO_Wait_Strategy *	ws_
	Strategy for waiting for the reply after sending the request. More...
int	bidirectional_flag_
	Have we sent any info on bidirectional information or have we received any info regarding making the connection served by this transport bidirectional. More...
TAO_Queued_Message *	head_
	Implement the outgoing data queue. More...
TAO_Queued_Message *	tail_
TAO_Incoming_Message_Queue	incoming_message_queue_
	Queue of the incoming messages.. More...
ACE_Time_Value	current_deadline_
	The queue will start draining no later than <queing_deadline_> if* the deadline is.* More...
long	flush_timer_id_
	The timer ID. More...
TAO_Transport_Timer	transport_timer_
	The adapter used to receive timeout callbacks from the Reactor. More...
ACE_Lock *	handler_lock_
	This is an `ACE_Lock` that gets initialized from `TAO_ORB_Core::resource_factory()->create_cached_connection_lock ()`. More...
int	id_
	This never never* changes over the lifespan, so we don't have to worry about locking it.* More...
unsigned long	purging_order_
	Used by the LRU, LFU and FIFO Connection Purging Strategies. More...
Private Methods
TAO_Transport_Cache_Manager &	transport_cache_manager (void)
	Helper method that returns the Transport Cache Manager. More...
int	drain_queue (void)
	As the outgoing data is drained this method is invoked to send as much of the current message as possible. More...
int	drain_queue_i (void)
	Implement drain_queue() assuming the lock is held. More...
int	queue_is_empty_i (void)
	This version assumes that the lock is already held. More...
int	drain_queue_helper (int &iovcnt, iovec iov[])
	A helper routine used in drain_queue_i(). More...
int	schedule_output_i (void)
	Schedule handle_output() callbacks. More...
int	cancel_output_i (void)
	Cancel handle_output() callbacks. More...
void	cleanup_queue (size_t byte_count)
	Exactly <byte_count> bytes have been sent, the queue must be cleaned up as potentially several messages have been completely sent out. More...
int	check_buffering_constraints_i (TAO_Stub *stub, int &must_flush)
	Copy the contents of a message block into a Queued_Message TAO_Queued_Message copy_message_block (const ACE_Message_Block mb); Check if the buffering constraints have been reached. More...
int	send_synchronous_message_i (const ACE_Message_Block message_block, ACE_Time_Value max_wait_time)
	Send a synchronous message, i.e. block until the message is on the wire. More...
int	send_reply_message_i (const ACE_Message_Block message_block, ACE_Time_Value max_wait_time)
	Send a reply message, i.e. do not block until the message is on the wire, but just return after adding them to the queue. More...
int	send_synch_message_helper_i (TAO_Synch_Queued_Message &s, ACE_Time_Value *max_wait_time)
	A helper method used by <send_synchronous_message_i> and <send_reply_message_i>. Reusable code that could be used by both the methods. More...
int	flush_timer_pending (void) const
	Check if the flush timer is still pending. More...
void	reset_flush_timer (void)
	The flush timer expired or was explicitly cancelled, mark it as not pending. More...
void	report_invalid_event_handler (const char *caller)
	Print out error messages if the event handler is not valid. More...
int	process_queue_head (TAO_Resume_Handle &rh)
int	notify_reactor (void)
ACE_Event_Handler *	invalidate_event_handler (void)
	Grab the mutex and then call invalidate_event_handler_i(). More...
void	send_connection_closed_notifications (void)
	Notify all the components inside a Transport when the underlying connection is closed. More...
void	close_connection_i (void)
	Implement close_connection() assuming the handler_lock_ is held. More...
void	close_connection_no_purge (void)
	Close the underlying connection, do not purge the entry from the map (supposedly it was purged already, trust the caller, yuck!). More...
void	close_connection_shared (int disable_purge, ACE_Event_Handler *eh)
	Close the underlying connection, implements the code shared by all the close_connection_ variants.* More...
	TAO_Transport (const TAO_Transport &)
	Prohibited. More...
void	operator= (const TAO_Transport &)
Friends
class	TAO_Block_Flushing_Strategy
	This class needs priviledged access to - queue_is_empty_i() - drain_queue_i(). More...
class	TAO_Reactive_Flushing_Strategy
	These classes need privileged access to: - schedule_output_i() - cancel_output_i(). More...
class	TAO_Leader_Follower_Flushing_Strategy
class	TAO_Transport_Cache_Manager
	This class needs priviledged access to: close_connection_no_purge (). More...

Detailed Description

Generic definitions for the Transport class.

The transport object is created in the Service handler constructor and deleted in the Service Handler's destructor!!

The main responsability of a Transport object is to encapsulate a connection, and provide a transport independent way to send and receive data. Since TAO is heavily based on the Reactor for all if not all its I/O the Transport class is usually implemented with a helper Connection Handler that adapts the generic Transport interface to the Reactor types.

The outgoing data path:

One of the responsibilities of the TAO_Transport class is to send out GIOP messages as efficiently as possible. In most cases messages are put out in FIFO order, the transport object will put out the message using a single system call and return control to the application. However, for oneways and AMI requests it may be more efficient (or required if the SYNC_NONE policy is in effect) to queue the messages until a large enough data set is available. Another reason to queue is that some applications cannot block for I/O, yet they want to send messages so large that a single write() operation would not be able to cope with them. In such cases we need to queue the data and use the Reactor to drain the queue.

Therefore, the Transport class may need to use a queue to temporarily hold the messages, and, in some configurations, it may need to use the Reactor to concurrently drain such queues.

Out of order messages:

TAO provides explicit policies to send 'urgent' messages. Such messages may put at the head of the queue. However, they cannot be sent immediately because the transport may already be sending another message in a reactive fashion.

Consequently, the Transport must also know if the head of the queue has been partially sent. In that case new messages can only follow the head. Only once the head is completely sent we can start sending new messages.

Waiting threads:

One or more threads can be blocked waiting for the connection to completely send the message. The thread should return as soon as its message has been sent, so a per-thread condition is required. This suggest that simply using a ACE_Message_Queue would not be enough: there is a significant amount of ancillary information, to keep on each message that the Message_Block class does not provide room for.

Blocking I/O is still attractive for some applications. First, my eliminating the Reactor overhead performance is improved when sending large blocks of data. Second, using the Reactor to send out data opens the door for nested upcalls, yet some applications cannot deal with the reentrancy issues in this case.

Timeouts:

Some or all messages could have a timeout period attached to them. The timeout source could either be some high-level policy or maybe some strategy to prevent denial of service attacks. In any case the timeouts are per-message, and later messages could have shorter timeouts. In fact, some kind of scheduling (such as EDF) could be required in a few applications.

Conclusions:

The outgoing data path consist in several components:

A queue of pending messages
A message currently being transmitted
A per-transport 'send strategy' to choose between blocking on write, blocking on the reactor or blockin on leader/follower.
A per-message 'waiting object'
A per-message timeout

The Transport object provides a single method to send request messages (send_request_message ()).

The incoming data path:

One of the main responsibilities of the transport is to read and process the incoming GIOP message as quickly and efficiently as possible. There are other forces that needs to be given due consideration. They are

Multiple threads should be able to tarverse along the same data path but should not be able to read from the same handle at the same time ie. the handle should not be shared between threads at any instant.
Reads on the handle could give one or more messages.
Minimise locking and copying overhead when trying to attack the above.

Parsing messages (GIOP) & processing the message:

The messages should be checked for validity and the right information should be sent to the higher layer for processing. The process of doing a sanity check and preparing the messages for the higher layers of the ORB are done by the messaging protocol.

Design forces and Challenges

To keep things as efficient as possible for medium sized requests, it would be good to minimise data copying and locking along the incoming path ie. from the time of reading the data from the handle to the application. We achieve this by creating a buffer on stack and reading the data from the handle into the buffer. We then pass the same data block (the buffer is encapsulated into a data block) to the higher layers of the ORB. The problems stem from the following (a) Data is bigger than the buffer that we have on stack (b) Transports like TCP do not guarantee availability of the whole chunk of data in one shot. Data could trickle in byte by byte. (c) Single read gives multiple messages

We solve the problems as follows

(a) First do a read with the buffer on stack. Query the underlying messaging object whether the message has any incomplete portion. If so, we just grow the buffer for the missing size and read the rest of the message. We free the handle and then send the message to the higher layers of the ORB for processing.

(b) If we block (ie. if we receive a EWOULDBLOCK) while trying to do the above (ie. trying to read after growing the buffer size) we put the message in a queue and return back to the reactor. The reactor would call us back when the handle becomes read ready.

(c) If we get multiple messages (possible if the client connected to the server sends oneways or AMI requests), we parse and split the messages. Every message is put in the queue. Once the messages are queued, the thread picks up one message to send to the higher layers of the ORB. Before doing that, if it finds more messages, it sends a notify to the reactor without resuming the handle. The next thread picks up a message from the queue and processes that. Once the queue is drained the last thread resumes the handle.

Sending Replies

We could use the outgoing path of the ORB to send replies. This would allow us to reuse most of the code in the outgoing data path. We were doing this till TAO-1.2.3. We run in to problems. When writing the reply the ORB gets flow controlled, and the ORB tries to flush the message by going into the reactor. This resulted in unnecessary nesting. The thread that gets into the Reactor could potentially handle other messages (incoming or outgoing) and the stack starts growing leading to crashes.

Solution to the nesting problem

The solution that we (plan to) adopt is pretty straight forward. The thread sending replies will not block to send the replies but queue the replies and return to the Reactor. (Note the careful usages of the terms "blocking in the Reactor" as opposed to "return back to the Reactor".

Member Enumeration Documentation

anonymous enum

Enumeration values:

TAO_ONEWAY_REQUEST

TAO_TWOWAY_REQUEST

TAO_REPLY

Constructor & Destructor Documentation

TAO_Transport::TAO_Transport ( CORBA::ULong tag,

TAO_ORB_Core * orb_core

)

default creator, requres the tag value be supplied.

TAO_Transport::~TAO_Transport ( void ) [virtual]

destructor.

TAO_Transport::TAO_Transport ( const TAO_Transport & ) [private]

Prohibited.

Member Function Documentation

TAO_Transport * TAO_Transport::_duplicate ( TAO_Transport * transport ) [static]

ACE_INLINE void TAO_Transport::bidirectional_flag ( int flag )

ACE_INLINE int TAO_Transport::bidirectional_flag ( void ) const

Get/Set the bidirectional flag.

ACE_INLINE TAO_Transport_Cache_Manager::HASH_MAP_ENTRY * TAO_Transport::cache_map_entry ( void )

ACE_INLINE void TAO_Transport::cache_map_entry ( TAO_Transport_Cache_Manager::HASH_MAP_ENTRY * entry )

Set/Get the Cache Map entry.

int TAO_Transport::cancel_output_i ( void ) [private]

Cancel handle_output() callbacks.

int TAO_Transport::check_buffering_constraints_i ( TAO_Stub * stub,

int & must_flush

) [private]

Copy the contents of a message block into a Queued_Message TAO_Queued_Message *copy_message_block (const ACE_Message_Block *mb); Check if the buffering constraints have been reached.

ACE_INLINE int TAO_Transport::check_event_handler_i ( const char * caller ) [protected]

Returns:
Returns -1 if not, 0 if it is.

void TAO_Transport::cleanup_queue ( size_t byte_count ) [private]

Exactly <byte_count> bytes have been sent, the queue must be cleaned up as potentially several messages have been completely sent out.
It leaves on head_ the next message to send out.

void TAO_Transport::close_connection ( void ) [virtual]

Call the implementation method after obtaining the lock.

void TAO_Transport::close_connection_i ( void ) [private]

Implement close_connection() assuming the handler_lock_ is held.

void TAO_Transport::close_connection_no_purge ( void ) [private]

Close the underlying connection, do not purge the entry from the map (supposedly it was purged already, trust the caller, yuck!).

void TAO_Transport::close_connection_shared ( int disable_purge,

ACE_Event_Handler * eh

) [private]

Close the underlying connection, implements the code shared by all the close_connection_* variants.

void TAO_Transport::connection_handler_closing ( void ) [virtual]

Method for the connection handler to signify that it is being closed and destroyed.

virtual TAO_Connection_Handler* TAO_Transport::connection_handler_i ( void ) [protected, pure virtual]

Reimplemented in TAO_IIOP_Transport.

int TAO_Transport::consolidate_extra_messages ( ACE_Message_Block & incoming,

TAO_Resume_Handle & rh

) [protected]

Called by parse_consolidate_message () if we have more messages in one read. Queue up the messages and try to process one of them, atleast at the head of them.

int TAO_Transport::consolidate_fragments ( TAO_Queued_Data * qd,

TAO_Resume_Handle & rh

) [protected]

Bala: Docu???
@

int TAO_Transport::consolidate_message ( ACE_Message_Block & incoming,

ssize_t missing_data,

TAO_Resume_Handle & rh,

ACE_Time_Value * max_wait_time

) [protected, virtual]

Consolidate the currently read message or consolidate the last message in the queue. The consolidation of the last message in the queue is done by calling consolidate_message_queue ().

int TAO_Transport::consolidate_message_queue ( ACE_Message_Block & incoming,

ssize_t missing_data,

TAO_Resume_Handle & rh,

ACE_Time_Value * max_wait_time

) [protected]

First consolidate the message queue. If the message is still not complete, try to read from the handle again to make it complete. If these dont help put the message back in the queue and try to check the queue if we have message to process. (the thread needs to do some work anyway :-)).

int TAO_Transport::drain_queue ( void ) [private]

As the outgoing data is drained this method is invoked to send as much of the current message as possible.
Returns 0 if there is more data to send, -1 if there was an error and 1 if the message was completely sent.

int TAO_Transport::drain_queue_helper ( int & iovcnt,

iovec iov[]

) [private]

A helper routine used in drain_queue_i().

int TAO_Transport::drain_queue_i ( void ) [private]

Implement drain_queue() assuming the lock is held.

virtual ACE_Event_Handler* TAO_Transport::event_handler_i ( void ) [protected, pure virtual]

Normally a concrete TAO_Transport object has-a ACE_Event_Handler member that function as an adapter between the ACE_Reactor framework and the TAO pluggable protocol framework.
In all the protocols implemented so far this role is fullfilled by an instance of ACE_Svc_Handler.

Todo:
Since we only use a limited functionality of ACE_Svc_Handler we could probably implement a generic adapter class (TAO_Transport_Event_Handler or something), this will reduce footprint and simplify the process of implementing a pluggable protocol.

Reimplemented in TAO_IIOP_Transport.

ACE_INLINE int TAO_Transport::flush_timer_pending ( void ) const [private]

Check if the flush timer is still pending.

int TAO_Transport::generate_locate_request ( TAO_Target_Specification & spec,

TAO_Operation_Details & opdetails,

TAO_OutputCDR & output

)

This is a request for the transport object to write a LocateRequest header before it is sent out.

int TAO_Transport::generate_request_header ( TAO_Operation_Details & opdetails,

TAO_Target_Specification & spec,

TAO_OutputCDR & msg

) [virtual]

This is a request for the transport object to write a request header before it sends out the request.

Reimplemented in TAO_IIOP_Transport.

int TAO_Transport::handle_input_i ( TAO_Resume_Handle & rh,

ACE_Time_Value * max_wait_time = 0,

int block = 0

) [virtual]

The ACE_Event_Handler adapter invokes this method as part of its handle_input() operation.

Todo:
: the method name is confusing! Calling it handle_input() would probably make things easier to understand and follow!

Once a complete message is read the Transport class delegates on the Messaging layer to invoke the right upcall (on the server) or the TAO_Reply_Dispatcher (on the client side).
Parameters:

max_wait_time In some cases the I/O is synchronous, e.g. a thread-per-connection server or when Wait_On_Read is enabled. In those cases a maximum read time can be specified.

block Is deprecated and ignored.

int TAO_Transport::handle_output ( void )

Callback method to reactively drain the outgoing data queue.

int TAO_Transport::handle_timeout ( const ACE_Time_Value & current_time,

const void * act

)

Parameters:

current_time The current time as reported from the Reactor

act The Asynchronous Completion Token. Currently it is interpreted as follows:

If the ACT is the address of this->current_deadline_ the queueing timeout has expired and the queue should start flushing.

Returns:
Returns 0 if there are no problems, -1 if there is an error
Todo:
In the future this function could be used to expire messages (oneways) that have been sitting for too long on the queue.

ACE_INLINE void TAO_Transport::id ( int id )

ACE_INLINE int TAO_Transport::id ( void ) const

If not set, this will return an integer representation of the this pointer for the instance on which it's called.

int TAO_Transport::idle_after_reply ( void ) [virtual]

Request is sent and the reply is received. Idle the transport now.

int TAO_Transport::idle_after_send ( void ) [virtual]

Request has been just sent, but the reply is not received. Idle the transport now.

ACE_Event_Handler * TAO_Transport::invalidate_event_handler ( void ) [private]

Grab the mutex and then call invalidate_event_handler_i().

virtual ACE_Event_Handler* TAO_Transport::invalidate_event_handler_i ( void ) [protected, pure virtual]

Typically, this just sets the pointer to the associated connection handler to zero, although it could also clear out any additional resources associated with the handler association.

Returns:
The old event handler

Reimplemented in TAO_IIOP_Transport.

int TAO_Transport::make_idle ( void )

Cache management.

TAO_Queued_Data * TAO_Transport::make_queued_data ( ACE_Message_Block & incoming ) [protected]

Make a queued data from the <incoming> message block.

virtual int TAO_Transport::messaging_init ( CORBA::Octet major,

CORBA::Octet minor

) [pure virtual]

Initialising the messaging object.
This would be used by the connector side. On the acceptor side the connection handler would take care of the messaging objects.
Reimplemented in TAO_IIOP_Transport.

virtual TAO_Pluggable_Messaging* TAO_Transport::messaging_object ( void ) [protected, pure virtual]

Return the messaging object that is used to format the data that needs to be sent.

Reimplemented in TAO_IIOP_Transport.

size_t TAO_Transport::missing_data ( ACE_Message_Block & incoming ) [protected]

Return if we have any missing data in the queue of messages or determine if we have more information left out in the presently read message to make it complete.

int TAO_Transport::notify_reactor ( void ) [private]

void TAO_Transport::operator= ( const TAO_Transport & ) [private]

ACE_INLINE TAO_ORB_Core * TAO_Transport::orb_core ( void ) const

Access the ORB that owns this connection.

int TAO_Transport::parse_consolidate_messages ( ACE_Message_Block & block,

TAO_Resume_Handle & rh,

ACE_Time_Value * max_wait_time = 0

) [protected]

Called by the handle_input_i (). This method is used to parse message read by the handle_input_i () call. It also decides whether the message needs consolidation before processing.

int TAO_Transport::parse_incoming_messages ( ACE_Message_Block & block ) [protected]

Method does parsing of the message if we have a fresh message in the <message_block> or just returns if we have read part of the previously stored message.

int TAO_Transport::process_parsed_messages ( TAO_Queued_Data * qd,

TAO_Resume_Handle & rh

) [protected]

Process the message by sending it to the higher layers of the ORB.

int TAO_Transport::process_queue_head ( TAO_Resume_Handle & rh ) [private]

void TAO_Transport::provide_handle ( ACE_Handle_Set & reactor_registered,

TAO_EventHandlerSet & unregistered

)

Called by the cache when the cache is closing in order to fill in a handle_set in a thread-safe manner.

Parameters:

reactor_registered the ACE_Handle_Set into which the transport should place any handle registered with the reactor

unregistered the TAO_EventHandlerSet into which the transport should place any event handler that is not registered with anyone

void TAO_Transport::purge_entry ( void )

Cache management.

ACE_INLINE void TAO_Transport::purging_order ( unsigned long value )

ACE_INLINE unsigned long TAO_Transport::purging_order ( void ) const

Get and Set the purging order. The purging strategy uses the set version to set the purging order.

ACE_INLINE int TAO_Transport::queue_is_empty ( void )

Returns:
1 if the queue is empty

int TAO_Transport::queue_is_empty_i ( void ) [private]

This version assumes that the lock is already held.
Use with care!

Returns:
1 if the queue is empty

int TAO_Transport::recache_transport ( TAO_Transport_Descriptor_Interface * desc )

recache ourselves in the cache.

ssize_t TAO_Transport::recv ( char * buffer,

size_t len,

const ACE_Time_Value * timeout = 0

)

This method serializes on handler_lock_, guaranteeing that only thread can execute it on the same instance concurrently.

Parameters:

buffer ORB allocated buffer where the data should be @ The ACE_Time_Value *s is just a place holder for now. It is not clear this this is the best place to specify this. The actual timeout values will be kept in the Policies.

virtual ssize_t TAO_Transport::recv_i ( char * buf,

size_t len,

const ACE_Time_Value * max_wait_time = 0

) [protected, pure virtual]

Parameters:

buffer ORB allocated buffer where the data should be @ The ACE_Time_Value *s is just a place holder for now. It is not clear this this is the best place to specify this. The actual timeout values will be kept in the Policies.

Reimplemented in TAO_IIOP_Transport.

int TAO_Transport::register_handler ( void )

Register the handler with the reactor.
This method is used by the Wait_On_Reactor strategy. The transport must register its event handler with the ORB's Reactor.

virtual int TAO_Transport::register_handler_i ( void ) [protected, pure virtual]

This method is used by the Wait_On_Reactor strategy.
The transport must register its event handler with the ORB's Reactor.

Todo:
: I think this method is pretty much useless, the connections are *always* registered with the Reactor, except in thread-per-connection mode. In that case putting the connection in the Reactor would produce unpredictable results anyway.

Reimplemented in TAO_IIOP_Transport.

void TAO_Transport::release ( TAO_Transport * transport ) [static]

void TAO_Transport::report_invalid_event_handler ( const char * caller ) [private]

Print out error messages if the event handler is not valid.

ACE_INLINE void TAO_Transport::reset_flush_timer ( void ) [private]

The flush timer expired or was explicitly cancelled, mark it as not pending.

int TAO_Transport::schedule_output_i ( void ) [private]

Schedule handle_output() callbacks.

ssize_t TAO_Transport::send ( iovec * iov,

int iovcnt,

size_t & bytes_transferred,

const ACE_Time_Value * timeout = 0

)

This method serializes on handler_lock_, guaranteeing that only thread can execute it on the same instance concurrently.
Often the implementation simply forwards the arguments to the underlying ACE_Svc_Handler class. Using the code factored out into ACE.
Be careful with protocols that perform non-trivial transformations of the data, such as SSLIOP or protocols that compress the stream.
Parameters:

mblk contains the data that must be sent. For each message block in the cont() chain all the data between rd_ptr() and wr_ptr() should be delivered to the remote peer.

timeout is the maximum time that the application is willing to wait for the data to be sent, useful in platforms that implement timed writes. The timeout value is obtained from the policies set by the application.

bytes_transferred should return the total number of bytes successfully transferred before the connection blocked. This is required because in some platforms and/or protocols multiple system calls may be required to send the chain of message blocks. The first few calls can work successfully, but the final one can fail or signal a flow control situation (via EAGAIN). In this case the ORB expects the function to return -1, errno to be appropriately set and this argument to return the number of bytes already on the OS I/O subsystem.

This call can also fail if the transport instance is no longer associated with a connection (e.g., the connection handler closed down). In that case, it returns -1 and sets errno to ENOENT.

void TAO_Transport::send_connection_closed_notifications ( void ) [private]

Notify all the components inside a Transport when the underlying connection is closed.

virtual ssize_t TAO_Transport::send_i ( iovec * iov,

int iovcnt,

size_t & bytes_transferred,

const ACE_Time_Value * max_wait_time = 0

) [protected, pure virtual]

Often the implementation simply forwards the arguments to the underlying ACE_Svc_Handler class.
Using the code factored out into ACE.
Be careful with protocols that perform non-trivial transformations of the data, such as SSLIOP or protocols that compress the stream.
Parameters:

iov contains the data that must be sent.

iovcnt is the number of iovec structures in the list where iov points.

bytes_transferred should return the total number of bytes successfully transferred before the connection blocked. This is required because in some platforms and/or protocols multiple system calls may be required to send the chain of message blocks. The first few calls can work successfully, but the final one can fail or signal a flow control situation (via EAGAIN). In this case the ORB expects the function to return -1, errno to be appropriately set and this argument to return the number of bytes already on the OS I/O subsystem.

timeout is the maximum time that the application is willing to wait for the data to be sent, useful in platforms that implement timed writes. The timeout value is obtained from the policies set by the application.

Reimplemented in TAO_IIOP_Transport.

virtual int TAO_Transport::send_message ( TAO_OutputCDR & stream,

TAO_Stub * stub = 0,

int message_semantics = TAO_Transport::TAO_TWOWAY_REQUEST,

ACE_Time_Value * max_wait_time = 0

) [pure virtual]

Once the ORB is prepared to receive a reply (see send_request() above), and all the arguments have been marshaled the CDR stream must be 'formatted', i.e.
the message_size field in the GIOP header can finally be set to the proper value.
Reimplemented in TAO_IIOP_Transport.

int TAO_Transport::send_message_block_chain ( const ACE_Message_Block * mb,

size_t & bytes_transferred,

ACE_Time_Value * max_wait_time = 0

)

Send a message block chain,.

int TAO_Transport::send_message_block_chain_i ( const ACE_Message_Block * mb,

size_t & bytes_transferred,

ACE_Time_Value * max_wait_time

)

Send a message block chain, assuming the lock is held.

int TAO_Transport::send_message_shared ( TAO_Stub * stub,

int message_semantics,

const ACE_Message_Block * message_block,

ACE_Time_Value * max_wait_time

) [virtual]

Parameters:

stub The object reference used for this operation, useful to obtain the current policies.

message_semantics If this is set to TAO_TWO_REQUEST this method will block until the operation is completely written on the wire. If it is set to other values this operation could return.

message_block The CDR encapsulation of the GIOP message that must be sent. The message may consist of multiple Message Blocks chained through the cont() field.

max_wait_time The maximum time that the operation can block, used in the implementation of timeouts.

Reimplemented in TAO_IIOP_Transport.

int TAO_Transport::send_message_shared_i ( TAO_Stub * stub,

int message_semantics,

const ACE_Message_Block * message_block,

ACE_Time_Value * max_wait_time

) [protected]

Implement send_message_shared() assuming the handler_lock_ is held.

int TAO_Transport::send_reply_message_i ( const ACE_Message_Block * mb,

ACE_Time_Value * max_wait_time

) [private]

Send a reply message, i.e. do not block until the message is on the wire, but just return after adding them to the queue.

virtual int TAO_Transport::send_request ( TAO_Stub * stub,

TAO_ORB_Core * orb_core,

TAO_OutputCDR & stream,

int message_semantics,

ACE_Time_Value * max_wait_time

) [pure virtual]

Preparing the ORB to receive the reply only once the request is completely sent opens the system to some subtle race conditions: suppose the ORB is running in a multi-threaded configuration, thread A makes a request while thread B is using the Reactor to process all incoming requests.
Thread A could be implemented as follows: 1) send the request 2) setup the ORB to receive the reply 3) wait for the request
but in this case thread B may receive the reply between step (1) and (2), and drop it as an invalid or unexpected message. Consequently the correct implementation is: 1) setup the ORB to receive the reply 2) send the request 3) wait for the reply
The following method encapsulates this idiom.

Todo:
This is generic code, it should be factored out into the Transport class.

Reimplemented in TAO_IIOP_Transport.

int TAO_Transport::send_synch_message_helper_i ( TAO_Synch_Queued_Message & synch_message,

ACE_Time_Value * max_wait_time

) [private]

A helper method used by <send_synchronous_message_i> and <send_reply_message_i>. Reusable code that could be used by both the methods.

int TAO_Transport::send_synchronous_message_i ( const ACE_Message_Block * mb,

ACE_Time_Value * max_wait_time

) [private]

Send a synchronous message, i.e. block until the message is on the wire.

ACE_INLINE CORBA::ULong TAO_Transport::tag ( void ) const

The OMG assigns unique tags (a 32-bit unsigned number) to each protocol.
New protocol tags can be obtained free of charge from the OMG, check the documents in corbafwd.h for more details.

int TAO_Transport::tear_listen_point_list ( TAO_InputCDR & cdr ) [virtual]

Extracts the list of listen points from the <cdr> stream. The list would have the protocol specific details of the ListenPoints.

Reimplemented in TAO_IIOP_Transport.

ACE_INLINE TAO_Transport_Mux_Strategy * TAO_Transport::tms ( void ) const

The role of the TAO_Transport_Mux_Strategy is described in more detail in that class' documentation.
Enough is to say that the class is used to control how many threads can have pending requests over the same connection. Multiplexing multiple threads over the same connection conserves resources and is almost required for AMI, but having only one pending request per connection is more efficient and reduces the possibilities of priority inversions.

TAO_Transport_Cache_Manager & TAO_Transport::transport_cache_manager ( void ) [private]

Helper method that returns the Transport Cache Manager.

ACE_INLINE TAO_Wait_Strategy * TAO_Transport::wait_strategy ( void ) const

The role of the TAO_Wait_Strategy is described in more detail in that class' documentation.
Enough is to say that the ORB can wait for a reply blocking on read(), using the Reactor to wait for multiple events concurrently or using the Leader/Followers protocol.

Friends And Related Function Documentation

friend class TAO_Block_Flushing_Strategy [friend]

This class needs priviledged access to - queue_is_empty_i() - drain_queue_i().

friend class TAO_Leader_Follower_Flushing_Strategy [friend]

friend class TAO_Reactive_Flushing_Strategy [friend]

These classes need privileged access to: - schedule_output_i() - cancel_output_i().

friend class TAO_Transport_Cache_Manager [friend]

This class needs priviledged access to: close_connection_no_purge ().

Member Data Documentation

int TAO_Transport::bidirectional_flag_ [protected]

Have we sent any info on bidirectional information or have we received any info regarding making the connection served by this transport bidirectional.
The flag is used as follows: + We dont want to send the bidirectional context info more than once on the connection. Why? Waste of marshalling and demarshalling time on the client. + On the server side -- once a client that has established the connection asks the server to use the connection both ways, we *dont* want the server to pack service info to the client. That is not allowed. We need a flag to prevent such a things from happening.
The value of this flag will be 0 if the client sends info and 1 if the server receives the info.

TAO_Transport_Cache_Manager::HASH_MAP_ENTRY* TAO_Transport::cache_map_entry_ [protected]

Our entry in the cache. We dont own this. It is here for our convinience. We cannot just change things around.

ACE_Time_Value TAO_Transport::current_deadline_ [protected]

The queue will start draining no later than <queing_deadline_> *if* the deadline is.

long TAO_Transport::flush_timer_id_ [protected]

The timer ID.

ACE_Lock* TAO_Transport::handler_lock_ [protected]

This is an ACE_Lock that gets initialized from TAO_ORB_Core::resource_factory()->create_cached_connection_lock ().
This way, one can use a lock appropriate for the type of system, i.e., a null lock for single-threaded systems, and a real lock for multi-threaded systems.

TAO_Queued_Message* TAO_Transport::head_ [protected]

Implement the outgoing data queue.

int TAO_Transport::id_ [protected]

This never *never* changes over the lifespan, so we don't have to worry about locking it.
HINT: Protocol-specific transports that use connection handler might choose to set this to the handle for their connection.

TAO_Incoming_Message_Queue TAO_Transport::incoming_message_queue_ [protected]

Queue of the incoming messages..

TAO_ORB_Core* TAO_Transport::orb_core_ [protected]

Global orbcore resource.

unsigned long TAO_Transport::purging_order_ [protected]

Used by the LRU, LFU and FIFO Connection Purging Strategies.

CORBA::ULong TAO_Transport::tag_ [protected]

IOP protocol tag.

TAO_Queued_Message* TAO_Transport::tail_ [protected]

TAO_Transport_Mux_Strategy* TAO_Transport::tms_ [protected]

Strategy to decide whether multiple requests can be sent over the same connection or the connection is exclusive for a request.

TAO_Transport_Timer TAO_Transport::transport_timer_ [protected]

The adapter used to receive timeout callbacks from the Reactor.

TAO_Wait_Strategy* TAO_Transport::ws_ [protected]

Strategy for waiting for the reply after sending the request.

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

Generated on Thu Oct 10 18:54:24 2002 for TAO by