ACE: ACE_DLL Class Reference

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_DLL::ACE_DLL ( bool close_handle_on_destruction = true ) [explicit]

Default constructor. By default, the close() operation on the object will be invoked before it is destroyed.

Parameters:

close_handle_on_destruction

Indicates whether or not the close() method will be called to close an open DLL when this object is destroyed. By default, close() will be called. Set this parameter to 0 for situations where the DLL's lifetime is controlled in a scope other than that of this ACE_DLL object. For example, termination by ACE_DLL_Manager via ACE::fini().

Definition at line 21 of file DLL.cpp.

References ACE_TRACE.

00022   : open_mode_ (0),
00023     dll_name_ (0),
00024     close_handle_on_destruction_ (close_handle_on_destruction),
00025     dll_handle_ (0),
00026     error_ (0)
00027 {
00028   ACE_TRACE ("ACE_DLL::ACE_DLL (int)");
00029 }

ACE_DLL::ACE_DLL	(	const ACE_TCHAR *	dll_name,
		int	open_mode = `ACE_DEFAULT_SHLIB_MODE`,
		bool	close_handle_on_destruction = `true`
	)			`[explicit]`

This constructor performs the actions of open() during construction.

Parameters:

	dll_name	The name or path of the DLL to load.
	open_mode	Flags to alter the actions taken when loading the DLL. The possible values are: `RTLD_LAZY` (this the default): loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand. `RTLD_NOW:` performs all necessary relocations when dll_name is first loaded RTLD_GLOBAL: makes symbols available for relocation processing of any other DLLs.
	close_handle_on_destruction	Indicates whether or not the close() method will be called to close an open DLL when this object is destroyed. By default, close() will be called. Set this parameter to 0 for situations where the DLL's lifetime is controlled in a scope other than that of this ACE_DLL object. For example, termination by ACE_DLL_Manager via ACE::fini().

Definition at line 74 of file DLL.cpp.

References ACE_ERROR, ACE_TEXT, ACE_TRACE, ACE::debug(), and LM_ERROR.

00077   : open_mode_ (open_mode),
00078     dll_name_ (0),
00079     close_handle_on_destruction_ (close_handle_on_destruction),
00080     dll_handle_ (0),
00081     error_ (0)
00082 {
00083   ACE_TRACE ("ACE_DLL::ACE_DLL");
00084 
00085   if (this->open (dll_name, this->open_mode_, close_handle_on_destruction) != 0
00086       && ACE::debug ())
00087     ACE_ERROR ((LM_ERROR,
00088                 ACE_TEXT ("ACE_DLL::open: error calling open: %s\n"),
00089                 this->error ()));
00090 }

ACE_DLL::ACE_DLL ( const ACE_DLL & )

Copy constructor.

Definition at line 31 of file DLL.cpp.

References ACE_ERROR, ACE_TEXT, ACE_TRACE, close_handle_on_destruction_, ACE::debug(), dll_name_, LM_ERROR, and open_mode_.

00032   : open_mode_ (0),
00033     dll_name_ (0),
00034     close_handle_on_destruction_ (false),
00035     dll_handle_ (0),
00036     error_ (0)
00037 {
00038   ACE_TRACE ("ACE_DLL::ACE_DLL (const ACE_DLL &)");
00039 
00040   if (rhs.dll_name_
00041       // This will automatically up the refcount.
00042       && this->open (rhs.dll_name_,
00043                      rhs.open_mode_,
00044                      rhs.close_handle_on_destruction_) != 0
00045       && ACE::debug ())
00046     ACE_ERROR ((LM_ERROR,
00047     ACE_TEXT ("ACE_DLL::copy_ctor: error: %s\n"),
00048     this->error ()));
00049 }

ACE_DLL::~ACE_DLL ( void )

Called when the DLL object is destroyed -- invokes close() if the close_handle_on_destruction flag was set to non-zero in the constructor or open() method.

Definition at line 96 of file DLL.cpp.

References ACE_TRACE, close(), and dll_name_.

00097 {
00098   ACE_TRACE ("ACE_DLL::~ACE_DLL");
00099 
00100   this->close ();
00101 
00102   // Normally delete()d in ACE_DLL::close().  However, that may not
00103   // occur if full ACE_DLL initialization is interrupted due to errors
00104   // (e.g. attempting to open a DSO/DLL that does not exist).  Make
00105   // sure this->dll_name_ is deallocated.
00106   delete [] this->dll_name_;
00107 }

int ACE_DLL::close ( void )

Call to close the DLL object.

Definition at line 198 of file DLL.cpp.

References ACE_TRACE, ACE_DLL_Manager::close_dll(), close_handle_on_destruction_, dll_handle_, dll_name_, error_, and ACE_DLL_Manager::instance().

Referenced by open_i(), and ~ACE_DLL().

00199 {
00200   ACE_TRACE ("ACE_DLL::close");
00201 
00202   int retval = 0;
00203 
00204   if (this->dll_handle_
00205       && this->close_handle_on_destruction_
00206       && this->dll_name_
00207       && (retval = ACE_DLL_Manager::instance ()->close_dll (this->dll_name_)) != 0)
00208     this->error_ = 1;
00209 
00210   // Even if close_dll() failed, go ahead and cleanup.
00211   this->dll_handle_ = 0;
00212   delete [] this->dll_name_;
00213   this->dll_name_ = 0;
00214   this->close_handle_on_destruction_ = false;
00215 
00216   return retval;
00217 }

ACE_TCHAR * ACE_DLL::error ( void ) const

Returns a pointer to a string explaining that an error occured. You will need to consult the error log for the actual error string returned by the OS.

Definition at line 222 of file DLL.cpp.

References ACE_TRACE, and ACE_OS::dlerror().

00223 {
00224   ACE_TRACE ("ACE_DLL::error");
00225   if (this->error_)
00226     {
00227       return ACE_OS::dlerror ();
00228     }
00229 
00230   return 0;
00231 }

ACE_SHLIB_HANDLE ACE_DLL::get_handle ( int become_owner = 0 ) const

Return the handle to the caller. If become_owner is non-0 then caller assumes ownership of the handle and the ACE_DLL object won't call close() when it goes out of scope, even if <close_handle_on_destruction> is set.

Definition at line 238 of file DLL.cpp.

References ACE_SHLIB_INVALID_HANDLE, ACE_TRACE, dll_handle_, and ACE_DLL_Handle::get_handle().

Referenced by ACE_Service_Repository::relocate_i().

00239 {
00240   ACE_TRACE ("ACE_DLL::get_handle");
00241 
00242   ACE_SHLIB_HANDLE handle = ACE_SHLIB_INVALID_HANDLE;
00243 
00244   if (this->dll_handle_)
00245     handle = this->dll_handle_->get_handle (become_owner);
00246 
00247   return handle;
00248 }

int ACE_DLL::open	(	const ACE_TCHAR *	dll_name,
		int	open_mode = `ACE_DEFAULT_SHLIB_MODE`,
		bool	close_handle_on_destruction = `true`
	)

This method opens and dynamically links a specified DLL.

Parameters:

	dll_name	The filename or path of the DLL to load. If a filename is given to `open()`, the `ACE::ldfind()` is used to locate DLLs via the following algorithms: (1) DLL filename expansion: `ACE::ldfind()` determines the name of the DLL by adding the appropriate prefix and suffix, e.g., it adds the `lib` prefix and .so suffix for Solaris and the .dll suffix for Windows and (2) DLL search path: `ACE::ldfind()` will also search for the designated DLL using the platform's DLL search path environment variable, e.g., it searches for DLLs using `LD_LIBRARY_PATH` on many UNIX systems and `PATH` on Windows.
	open_mode	Flags to alter the actions taken when loading the DLL. The possible values are: `RTLD_LAZY` (this the default): loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand. `RTLD_NOW:` performs all necessary relocations when dll_name is first loaded RTLD_GLOBAL: makes symbols available for relocation processing of any other DLLs.
	close_handle_on_destruction	Indicates whether or not the close() method will be called to close an open DLL when this object is destroyed. By default, close() will be called. Set this parameter to 0 for situations where the DLL's lifetime is controlled in a scope other than that of this ACE_DLL object. For example, termination by ACE_DLL_Manager via ACE::fini().

Return values:

	-1	On failure
	0	On success.

Definition at line 121 of file DLL.cpp.

References ACE_TRACE, and open_i().

00124 {
00125   ACE_TRACE ("ACE_DLL::open");
00126 
00127   return open_i (dll_filename, open_mode, close_handle_on_destruction);
00128 }

int ACE_DLL::open_i	(	const ACE_TCHAR *	dll_name,
		int	open_mode = `ACE_DEFAULT_SHLIB_MODE`,
		bool	close_handle_on_destruction = `true`,
		ACE_SHLIB_HANDLE	handle = `0`
	)			`[private]`

Definition at line 131 of file DLL.cpp.

References ACE_ERROR, ACE_TEXT, ACE_TRACE, close(), close_handle_on_destruction_, ACE::debug(), dll_handle_, dll_name_, error_, ACE_DLL_Manager::instance(), LM_ERROR, ACE_DLL_Manager::open_dll(), open_mode_, ACE_OS::strcmp(), and ACE::strnew().

Referenced by open(), and set_handle().

00135 {
00136   ACE_TRACE ("ACE_DLL::open_i");
00137 
00138   this->error_ = 0;
00139 
00140   if (!dll_filename)
00141     {
00142       if (ACE::debug ())
00143         ACE_ERROR ((LM_ERROR,
00144                     ACE_TEXT ("ACE_DLL::open_i: dll_name is %s\n"),
00145                     this->dll_name_ == 0 ? ACE_TEXT ("(null)")
00146         : this->dll_name_));
00147       return -1;
00148     }
00149 
00150   if (this->dll_handle_)
00151     {
00152       // If we have a good handle and its the same name, just return.
00153       if (ACE_OS::strcmp (this->dll_name_, dll_filename) == 0)
00154         return 0;
00155       else
00156         this->close ();
00157     }
00158 
00159   if (!this->dll_name_)
00160     this->dll_name_ = ACE::strnew (dll_filename);
00161 
00162   this->open_mode_ = open_mode;
00163   this->close_handle_on_destruction_ = close_handle_on_destruction;
00164 
00165   this->dll_handle_ = ACE_DLL_Manager::instance()->open_dll (this->dll_name_,
00166                                                              this->open_mode_,
00167                                                              handle);
00168 
00169   if (!this->dll_handle_)
00170     this->error_ = 1;
00171 
00172   return this->error_ ? -1 : 0;
00173 }

ACE_DLL & ACE_DLL::operator= ( const ACE_DLL & rhs )

Allow assignment.

Definition at line 54 of file DLL.cpp.

References ACE_TRACE, close_handle_on_destruction_, dll_handle_, dll_name_, error_, and open_mode_.

00055 {
00056   ACE_TRACE ("ACE_DLL::operator= (const ACE_DLL &)");
00057 
00058   ACE_DLL tmp (rhs);
00059 
00060   std::swap (this->open_mode_, tmp.open_mode_);
00061   std::swap (this->dll_name_, tmp.dll_name_);
00062   std::swap (this->close_handle_on_destruction_,
00063              tmp.close_handle_on_destruction_);
00064   std::swap (this->dll_handle_, tmp.dll_handle_);
00065   std::swap (this->error_, tmp.error_);
00066 
00067   return *this;
00068 }

int ACE_DLL::set_handle	(	ACE_SHLIB_HANDLE	handle,
		bool	close_handle_on_destruction = `true`
	)

Set the handle for the DLL object. By default, the close().

Definition at line 254 of file DLL.cpp.

References ACE_TRACE, ACE_UNIQUE_NAME_LEN, open_i(), and ACE_OS::unique_name().

Referenced by ACE_Service_Type::ACE_Service_Type().

00256 {
00257   ACE_TRACE ("ACE_DLL::set_handle");
00258 
00259   // Create a unique name.  Note that this name is only quaranteed
00260   // to be unique for the life of this object.
00261   ACE_TCHAR temp[ACE_UNIQUE_NAME_LEN];
00262   ACE_OS::unique_name (this, temp, ACE_UNIQUE_NAME_LEN);
00263 
00264   return this->open_i (temp, 1, close_handle_on_destruction, handle);
00265 }

void * ACE_DLL::symbol	(	const ACE_TCHAR *	symbol_name,
		int	ignore_errors = `0`
	)

Look up a named symbol in the DLL. DLL must be successfully opened before calling symbol().

Parameters:

	symbol_name	The symbol name to look up.
	ignore_errors	If set to 1, allows you to probe a dll without generating error messages in the log. Handy for determining the capabilities of a library.

Returns:: Returns the value of symbol_name if it is a valid symbol in the DLL. Otherwise, returns 0.

Definition at line 178 of file DLL.cpp.

References ACE_TRACE, dll_handle_, error_, and ACE_DLL_Handle::symbol().

00179 {
00180   ACE_TRACE ("ACE_DLL::symbol");
00181 
00182   this->error_ = 0;
00183 
00184   void *sym = 0;
00185   if (this->dll_handle_)
00186     sym = this->dll_handle_->symbol (sym_name, ignore_errors);
00187 
00188   if (!sym)
00189     this->error_ = 1;
00190 
00191   return sym;
00192 }

bool ACE_DLL::close_handle_on_destruction_

This flag keeps track of whether we should close the handle automatically when the object is destroyed.

Definition at line 184 of file DLL.h.

Referenced by ACE_DLL(), close(), open_i(), and operator=().

ACE_DLL_Handle* ACE_DLL::dll_handle_

Definition at line 186 of file DLL.h.

Referenced by close(), get_handle(), open_i(), operator=(), and symbol().

ACE_TCHAR* ACE_DLL::dll_name_

Keep track of the name of the loaded dll, so it can be used to remove framework components, singletons that live in the dll, prior to unloading the dll in the close() method.

Definition at line 180 of file DLL.h.

Referenced by ACE_DLL(), close(), open_i(), operator=(), ACE_Service_Gestalt::process_directive_i(), and ~ACE_DLL().

bool ACE_DLL::error_

Flag to record if the last operation had an error.

Definition at line 189 of file DLL.h.

Referenced by close(), open_i(), operator=(), and symbol().

int ACE_DLL::open_mode_

Open mode.

Definition at line 175 of file DLL.h.

Referenced by ACE_DLL(), open_i(), and operator=().

ACE_DLL Class Reference

Public Member Functions

Public Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation


Public Member Functions
	ACE_DLL (bool close_handle_on_destruction=true)
ACE_DLL &	operator= (const ACE_DLL &rhs)
	Allow assignment.
	ACE_DLL (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, bool close_handle_on_destruction=true)
	ACE_DLL (const ACE_DLL &)
	Copy constructor.
int	open (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, bool close_handle_on_destruction=true)
int	close (void)
	Call to close the DLL object.
	~ACE_DLL (void)
void *	symbol (const ACE_TCHAR *symbol_name, int ignore_errors=0)
ACE_TCHAR *	error (void) const
ACE_SHLIB_HANDLE	get_handle (int become_owner=0) const
int	set_handle (ACE_SHLIB_HANDLE handle, bool close_handle_on_destruction=true)
	Set the handle for the DLL object. By default, the close().
Public Attributes
int	open_mode_
	Open mode.
ACE_TCHAR *	dll_name_
bool	close_handle_on_destruction_
ACE_DLL_Handle *	dll_handle_
bool	error_
	Flag to record if the last operation had an error.
Private Member Functions
int	open_i (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, bool close_handle_on_destruction=true, ACE_SHLIB_HANDLE handle=0)