Hello all,
attached is a draft specifying a minor enhancement to pluginlib which revises the load/create/unload life cycle of libraries.
It enables automatic bookkeeping of created instance and automatically triggers unloading the library when the last instance goes out of scope.
The proposal deprecates one existing method which can lead to difficult usage pattern (ranging from never unloading a library to unloading a library while it is still in use).
The HTML version will be available soon:
http://ros.org/reps/rep-0121.html
Please send comments, questions or feedback.
Due to the small scope I am also asking for your vote (according to the guidelines stated at
http://www.ros.org/reps/rep-0010.html).
Best regards,
Dirk
REP: 121
Title: Automatic unloading of libraries for pluginlib
Version: $Revision: 1 $
Last-Modified: $Date: 2012-02-06 13:00:00 +0200 (Mon, 6 Feb 2012) $
Author: Dirk Thomas
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 6-Feb-2012
ROS-Version: Fuerte
Post-History: 6-Feb-2012
Abstract
========
In REP 116 [1]_ pluginlib was enhance to support unloading
libraries within the life cycle of the ClassLoader. In this REP
the interface the user of pluginlib uses is revised to better
support the load/create/unload cycle of shared libraries in order to
permit unloading the library from memory when it is no more used.
Current implementation
======================
The ClassLoader of pluginlib exposes the following methods:
* loadLibraryForClass(const std::string& lookup_name)
Loads the library (if not already loaded) and increments a counter
which is specific for that library.
* unloadLibraryForClass(const std::string& lookup_name)
Decrements the counter of that library and unloads the library if
the counter reaches zero.
These two methods provide a clear interface and semantic regarding
the life cycle of libraries.
In order to instantiate a class from a library the user calls:
* T* createClassInstance(const std::string& lookup_name, bool auto_load = true)
Creates an instance of type T and returns a pointer. The ownership
of the object is transfered to the caller. If autoloading is
disabled the pointer might be null if the library has not been
loaded before. If autoloading is enabled (default) the library is
only loaded if it has not been loaded before.
The issue with this implementation is that the user has no indication
if createClassInstance() increased the library counter implicitly or
not. Furthermore the user has to take care about the correct point
in time when calling unloadLibraryForClass().
Specification
=============
In order to provide a clear semantic for creating instances a new
method is introduced. Internally it will always call
loadLibraryForClass(). In order to receive an event when the
instance is no more required it returns a boost::shared_ptr. The
deleter will trigger an unloadLibraryForClass() call.
* boost::shared_ptr<T> createInstance(const std::string& lookup_name)
The method has no autoloading flag as the user can easily check if
the library is not loaded before trying to create an instance. This
reduces the complexity and potential side effects.
The existing method createClassInstance() will be deprecated and
later on removed.
The common usage patterns would be:
* Use only createInstance() (once or multiple times) and let the
boost deleter take care about unloading the library.
or
* Use loadLFC() before calling createInstance() and unloadLFC() to
trigger the unloading manually.
Backwards Compatibility
=======================
The side effects of the existing and createCI() method in combination
with unloadLFC() are not fixable without potentially breaking existing
application. Therefore the implementation of createClassInstance()
is not altered in any way but deprected. The additions will induce
no effect on existing code.
Reference implementation
========================
Reference implementation code is locate in the HG repository.
See the diff [2]_ for detailed information.
References
==========
.. [1] REP 116
(
http://ros.org/reps/rep-0116.html)
.. [2] Patch
(
https://kforge.ros.org/common/pluginlib/rev/f4a728b1a365)
Copyright
=========
This document has been placed in the public domain.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End:
(text/plain)