// -*- Mode: C++; -*-
// Package : omniORB2
// giopStrand.h Created on: 05/01/2001
// Author : Sai Lai Lo (sll)
//
// Copyright (C) 2001 AT&T Laboratories Cambridge
//
// This file is part of the omniORB library
//
// The omniORB library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Library General Public
// License as published by the Free Software Foundation; either
// version 2 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Library General Public License for more details.
//
// You should have received a copy of the GNU Library General Public
// License along with this library; if not, write to the Free
// Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
// 02111-1307, USA
//
//
// Description:
// *** PROPRIETORY INTERFACE ***
//
/*
$Log: giopStrand.h,v $
Revision 1.1.6.4 2006/07/18 16:21:23 dgrisby
New experimental connection management extension; ORB core support
for it.
Revision 1.1.6.3 2006/07/02 22:52:05 dgrisby
Store self thread in task objects to avoid calls to self(), speeding
up Current. Other minor performance tweaks.
Revision 1.1.6.2 2006/06/22 13:53:49 dgrisby
Add flags to strand.
Revision 1.1.6.1 2003/03/23 21:03:46 dgrisby
Start of omniORB 4.1.x development branch.
Revision 1.1.4.10 2002/08/21 06:23:15 dgrisby
Properly clean up bidir connections and ropes. Other small tweaks.
Revision 1.1.4.9 2001/09/19 17:26:46 dpg1
Full clean-up after orb->destroy().
Revision 1.1.4.8 2001/09/10 17:43:11 sll
Replaced the non-thread safe resetIdleCounter with startIdleCounter and
stopIdleCounter. Added orderly_closed to indicate that a stand is orderly
closed because a GIOP CloseConnection message has been received.
Revision 1.1.4.7 2001/08/29 17:51:06 sll
Updated description for gatekeeper_checked.
Revision 1.1.4.6 2001/08/17 17:10:05 sll
Modularise ORB configuration parameters.
Revision 1.1.4.5 2001/08/03 17:43:19 sll
Make sure dll import spec for win32 is properly done.
Revision 1.1.4.4 2001/07/31 16:28:01 sll
Added GIOP BiDir support.
Revision 1.1.4.3 2001/07/13 15:20:56 sll
New member safeDelete is now the only method to delete a strand.
Revision 1.1.4.2 2001/06/13 20:11:37 sll
Minor update to make the ORB compiles with MSVC++.
Revision 1.1.4.1 2001/04/18 17:19:00 sll
Big checkin with the brand new internal APIs.
Revision 1.1.2.1 2001/02/23 16:47:04 sll
Added new files.
*/
#ifndef __GIOPSTRAND_H__
#define __GIOPSTRAND_H__
#include <omniORB4/omniTransport.h>
#ifdef _core_attr
# error "A local CPP macro _core_attr has already been defined."
#endif
#if defined(_OMNIORB_LIBRARY)
# define _core_attr
#else
# define _core_attr _OMNIORB_NTDLL_IMPORT
#endif
OMNI_NAMESPACE_BEGIN(omni)
class giopStream;
class giopStreamImpl;
class giopWorker;
class giopServer;
class GIOP_S;
struct giopStream_Buffer;
////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////
class giopStreamList {
public:
giopStreamList* next;
giopStreamList* prev;
inline giopStreamList() {
next = this;
prev = this;
}
inline void insert(giopStreamList& head) {
next = head.prev->next;
head.prev->next = this;
prev = head.prev;
head.prev = this;
}
inline void remove() {
prev->next = next;
next->prev = prev;
next = prev = this;
}
static inline CORBA::Boolean is_empty(giopStreamList& head) {
return (head.next == &head);
}
private:
giopStreamList(const giopStreamList&);
giopStreamList& operator=(const giopStreamList&);
};
////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////
class giopStrand : public Strand {
public:
giopStrand(const giopAddress*);
// Ctor for an active strand. I.e. those that are used to connect to
// a remote address space.
// When a connection is establshed, the reference count goes to 1.
//
// No thread safety precondition
giopStrand(giopConnection*,giopServer*);
// Ctor for a passive strand. I.e. those that are created because a
// client has connected to this address space.
// Increment the reference count on the connection.
//
// No thread safety precondition
public:
CORBA::Boolean safeDelete(CORBA::Boolean forced = 0);
// This should be the *ONLY* method to call to delete a strand.
// Return TRUE if the strand can be considered deleted.
//
// The function checks if this connection is satisfied before it returns
// true:
//
// giopStreamList::is_empty(clients) &&
// giopStreamList::is_empty(servers) &&
// giopStream::noLockWaiting(this)
//
// If the function returns true, the above condition becomes an invariant
// and should not be violated until the dtor of the strand is called.
//
// The <forced> flag, if set explicitly to 1, causes the function to
// skip checking for the above condition. Instead it just go ahead as if
// the condition is met. This flag is used for internal implementation
// and should not be used by any client of this class.
//
// Internally, the strand may stays on a bit longer until the connection's
// reference count goes to 0 as well.
//
// Thread Safety preconditions:
// Caller must hold omniTransportLock unless forced == 1.
private:
CORBA::Boolean pd_safelyDeleted;
public:
CORBA::Boolean deletePending();
// Return true, if safeDelete() has been called and it returns true.
//
// If this method returns true, the following invariant is always true
// until the strand is deleted:
//
// giopStreamList::is_empty(clients) &&
// giopStreamList::is_empty(servers) &&
// giopStream::noLockWaiting(this)
//
// The caller must not do anything that would cause the strand to violate
// this invariant. For example, attempt or wait to acquire a lock on the
// strand, or to queue any GIOP_S or GIOP_C object to the strand.
//
//
// Thread Safety preconditions:
// Caller must hold omniTransportLock.
GIOP_S* acquireServer(giopWorker*);
// Acquire a GIOP_S from the strand. Normally this is only done on
// passive strands. However, it can also be used for active strands when
// they become birectional, i.e. BiDir == 1.
//
// Return 0 if a GIOP_S cannot be acquired.
//
// Thread Safety preconditions:
// Caller must not hold omniTransportLock, it is used internally for
// synchronisation.
void releaseServer(IOP_S*);
// Release the GIOP_S to the strand. The GIOP_S must have been acquired
// previously through acquireServer from this strand. Passing in a GIOP_S
// from a different strand would result in undefined behaviour.
//
// Thread Safety preconditions:
// Caller must not hold omniTransportLock, it is used internally for
// synchronisation.
enum State { ACTIVE, // The strand is in active use
DYING, // Something terminally wrong has happened to the
// strand, it should be removed at the earliest
// convenient time.
TIMEDOUT // This strand can still be used when required but
// it can also be removed if resources is scarce.
};
State state() const { return pd_state; }
// No thread safety precondition, use with extreme care
void state(State s) { pd_state = s; }
// No thread safety precondition, use with extreme care
/////////////////////////////////////////////////////////////////////////
CORBA::Boolean startIdleCounter();
// returns 1 if the idle counter has been successfully started.
// returns 0 if the idle counter is already active or has already expired.
//
// Thread Safety preconditions:
// Caller must hold omniTransportLock.
CORBA::Boolean stopIdleCounter();
// returns 1 if the idle counter has been successfully stopped.
// returns 0 if the idle counter has already expired and cannot be reset.
// In the latter case, the caller should assume that the strand is about
// to be shutdown and hence should cleanup its usage accordingly.
//
// Thread Safety preconditions:
// Caller must hold omniTransportLock.
////////////////////////////////////////////////////////////////////////
// When idlebeats go to 0, the strand has been idle for a sufficently
// long time and should be deleted.
// This variable SHOULD NOT be manipulated outside the implementation of
// giopStrand.
CORBA::Long idlebeats;
giopStreamList servers;
giopStreamList clients;
// a strand may have more than one giopStream instances associated with
// it. Mostly this is because from GIOP 1.2 onwards, requests can be
// interleaved on associated connection. Each of these request is
// represented by a giopStream instance. They are linked together by
// servers and clients.
// servers - all the GIOP_S that is serving calls for this strand
// clients - all the GIOP_C that is doing invocation using this strand
//
// Except when a strand is used to support bidirectional GIOP, only one of
// the list will be populated (because plain GIOP is asymetric and one
// end is either a client or a server but not both). With bidirectional GIOP,
// both list may be populated.
inline CORBA::Boolean isClient() { return (address != 0); }
// Return TRUE if this is an active strand on the client side. Unless
// biDir is TRUE, only those messages expected by a GIOP client can be
// received from this connection.
const giopAddress* address;
// address is provided as ctor arg if this is a active strand, otherwise
// it is 0.
giopConnection* connection;
// connection is provided as ctor arg if this is a passive strand
// otherwise it is obtained by address->connect().
giopServer* server;
// server is provided as ctor arg if this is a passive strand
// otherwise it is 0.
CORBA::ULong flags;
// Flags for use by interceptors. See giopStrandFlags.h for
// allocated flags values.
// Initialised to 0 in the constructor.
CORBA::Boolean biDir;
// Indicate if the strand is used for bidirectional GIOP.
CORBA::Boolean gatekeeper_checked;
// only applies to passive strand. TRUE(1) means that the serverTransportRule
// has been checked. This flag is set by giopWorker and is
// not manipulated by the strand class.
CORBA::Boolean first_use;
// only applies to active strand. TRUE(1) means this connection has
// not been used for any purpose before.
// This flag is set to 1 by ctor and reset to 0 by GIOP_C.
CORBA::Boolean first_call;
// only applies to active strand. TRUE(1) means this connection has
// not yet been used to start a normal invocation. It may have been
// used for other purposes, e.g. a locate request.
// This flag is set to 1 by ctor and reset to 0 by GIOP_C.
CORBA::Boolean orderly_closed;
// only applies to active strand. TRUE(1) means a GIOP CloseConnection
// was received and cause the strand state to change to DYING.
// This flag is set to 0 by ctor and set to 1 by the giopImpl?? classes.
CORBA::Boolean biDir_initiated;
// only applies to active strand. TRUE(1) means biDir service context
// has been sent for this connection.
// This flag is initialised to 0 by ctor and set to 1 by
// setBiDirServiceContext.
CORBA::Boolean biDir_has_callbacks;
// only applies to active bidirectional strand. TRUE(1) means call back
// objects have been sent through this connection. In other words, the
// connection may receive invocations on these objects from the other
// end.
// This flag is initialised to 0 by ctor and set to 1 by
// omniObjRef::_marshal.
////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////
// The following are data structures used by the giopStream instances
// associated with this strand AND SHOULD NOT BE manipulated by the Strand
// class!!!
CORBA::Boolean tcs_selected;
omniCodeSet::TCS_C* tcs_c;
omniCodeSet::TCS_W* tcs_w;
GIOP::Version version;
giopStreamImpl* giopImpl;
// The transmission codesets for char, wchar, string and wstring are
// selected by the client based on the codeset info in the IOR. The
// client informs the server of its selection using a codeset service
// context. This is done only once per lifetime of a connection (strand).
// If <tcs_selected> == 1,
// <tcs_c>, <tcs_w> and <version> records the chosen code set convertors
// and the GIOP version for which the convertors apply.
// conditional variables and counters to implement giopStream locking
// functions.
omni_tracedcondition rdcond;
int rd_nwaiting;
int rd_n_justwaiting;
omni_tracedcondition wrcond;
int wr_nwaiting;
CORBA::ULong newSeqNumber();
// Return a number suitable for use as the GIOP request id.
//
// Thread Safety preconditions:
// Caller must hold omniTransportLock.
private:
CORBA::ULong seqNumber;
// monotonically increasing number to be used as the GIOP request id.
public:
giopStream_Buffer* head;
giopStream_Buffer* spare;
public:
static _core_attr StrandList active;
static _core_attr StrandList active_timedout;
static _core_attr StrandList passive;
// Throughout the lifetime of a strand, it is a member of one and only one
// of the lists:
// active - the ORB uses this connection in the role of a client
// it is 'active' in the sense that the connection was
// initiated by this ORB
// active_timedout - the connection was previously active and has been
// idled for some time. It will be deleted soon.
// passive - the ORB uses this connection in the role of a server
// it is 'passive' because the connection was initiated
// by the remote party.
//
static _core_attr CORBA::ULong idleOutgoingBeats;
// Number to instantiate idlebeats when the active strand becomes idle.
static _core_attr CORBA::ULong idleIncomingBeats;
// idleIncomingBeats * scanPeriod == no. of sec. a passive strand should
// be allowed to stay idle.
public:
void deleteStrandAndConnection(CORBA::Boolean forced=0);
// Decrement connection's reference count. If it goes to 0, delete
// this strand as well. This call ensures that both the strand and
// connection die at the same time.
//
// Thread Safety preconditions:
// Caller must hold omniTransportLock unless forced == 1.
#ifdef __GNUG__
friend class keep_gcc_happy;
#endif
private:
virtual ~giopStrand();
State pd_state;
giopStrand(const giopStrand&);
giopStrand& operator=(const giopStrand&);
};
OMNI_NAMESPACE_END(omni)
#undef _core_attr
#endif // __GIOPSTRAND_H__
