smtpthread/SMTPConnectionPool.h

// DOCUMENT:  SMTPConnectionPool-Class
// VERSION:   $Revision: 1.7 $
// DATE:      $Date: 2007-11-01 08:44:12 $
// AUTHOR:    M.Beranek
// COPYRIGHT: M.Beranek

#ifndef _SMTPCONNECTIONPOOL_H
#define _SMTPCONNECTIONPOOL_H

#include <string>
#include <vector>
#include "SMTPConnection.h"
#include "ThreadedSMTPConnection.h"

namespace SmtpThread
{
    /**
     * SMTPConnectionPool-Class.
     *
     * The SMTPConnectionPool sets up an amount of SMTPConnections.
     * These connections are threaded objects and run each in a seperate
     * thread. To send a message, just utilize the sendMail-method.
     * The SMTPConnectionPool then tries to find a ready connection
     * and delegates the message to this connection.
     * 
     * Typical usage:
     * <code><pre>
     * \#include <iostream>
     * \#include <sstream>
     * \#include <stdlib.h>
     * \#include <string>
     * \#include <stdio.h>
     * \#include <stdlib.h>
     * \#include <smtpthread/SMTPConnectionPool.h>
     * 
     * using namespace std;
     * using namespace SmtpThread;
     * 
     * int main(int argc, char** argv) {
     * 
     *     string ip = "127.0.0.1";      // SMTP-Server
     *     string host = "localhost";    // for HELO-command
     *     string to = "you@localhost";  // sender-email
     *     string from = "me@localhost"; // recipient-email
     *     string port = "25";           // SMTP-port
     * 
     *     using namespace std;
     * 
     *     mailbody  = "From: \"me@localhost\"\n";
     *     mailbody += "To: \"you@remotehost\"\n";
     *     mailbody += "Subject: This is a test\n";
     *     mailbody += "\n";
     *     mailbody += "This is the first line of the body.\n";
     *     mailbody += "This is the second line of the body.\n";
     * 
     *     SMTPConnectionPool pool;
     * 
     *     pool.setMyHostname( host );
     *     pool.setSMTPHost( ip );
     *     pool.setSMTPPort( portNumber );
     *     pool.setMaxPoolSize( 100 );
     *     pool.setMinPoolSize( 1 );
     *     pool.setPoolSize( 10 );
     *     pool.setOptimizePool( true );
     * 
     *     int success = 0;
     *     int error   = 0;
     *     int result  = 0;
     * 
     *     for( int idx = 0; idx < 1000; idx++ )
     *     {
     *         result = pool.sendMail( from, to, mailbody  );
     *         if( result == 0 ) ++success;
     *         else ++error;
     *     }
     * 
     *     cout << "Success: " << success << endl;
     *     cout << "Errors:  " << error   << endl;
     * 
     * }
     * </pre></code>
     */
    class SMTPConnectionPool
    {
    public:
        /**
         * Default Constructor.
         */
        SMTPConnectionPool();
        
        /**
         * Default Destructor.
         */
        ~SMTPConnectionPool();
        
        /**
         * Send an email to the connection-pool.
         * @param string from sender-email, used in the SMTP-dialog.
         * @param string to receiver-email, used in the SMTP-dialog.
         * @param string msg email-body to send, including additional headers.
         */
        int sendMail( string& from, string& to, string& msg );
        
        /**
         * Sets the pool-size.
         * The pool-size is the number of SMTP-connectons, which are
         * connected to the SMTP-Server.
         * @param unsigned long poolSize number of SMTP-connections.
         */
        void setPoolSize( unsigned long );
        
        /**
         * Returns the pool-size.
         * @return unsigned long pool-size.
         */
        unsigned long getPoolSize();
        
        /**
         * Sets the IP-address of the SMTP-host.
         *
         * NOTE: Must be an IP-address and no domain-name.
         *
         * @param string host IP-address of the SMTP-server.
         */
        void setSMTPHost( string host );
        
        /**
         * Sets the port-number to connect to. Defaults to 25.
         * @param int port port-number of the remote SMTP-server.
         */
        void setSMTPPort( int port );
        
        /**
         * Sets the hostname, which is send in the HELO-commend.
         * @param string myname hostname of the mail-sending-host.
         */
        void setMyHostname( string myname );
        
        /**
         * Tells the pool wether or not to optimize the pool-size.
         *
         * Optimizing tries to find a pool-size, which has enough
         * connections so that a new sendmail-command does not have to
         * wait for previous connection to finish.
         *
         * The optimal pool-size is calculated and set, if within the
         * upper and lower limits set with "setMinPoolSize" and
         * "setMaxPoolSize".
         *
         * Please remember, that changing the pool-size also affects
         * allocating or deallocating of new/existing objects. This
         * results in small performanc-impacts. The bast way is to
         * already know the optimal pool-size, initialize the pool
         * with that size and disable optimizing the pool.
         *
         * NOTE: Optimizing the pool-size is not a trivial task.
         * The algorithm used in this implementation, is a rather
         * simple approach. Works for me, but might not be smart
         * enough for you.
         *
         * @param bool opt true / false = optimize / do not optimize the pool-size.
         * @see SMTPConnectionPool::setMinPoolSize
         * @see SMTPConnectionPool::setMaxPoolSize
         */
        void setOptimizePool( bool );
        
        /**
         * Sets the minimum size of the connection-pool.
         * Takes effect only, when pool-optimization is active.
         * @param long minimum minimal pool-size.
         */
        void setMinPoolSize( long );
        
        /**
         * Sets the maximum size of the connection-pool.
         * Takes effect only, when pool-optimization is active.
         * @param long maximum maximal pool-size.
         */
        void setMaxPoolSize( long );
        
    private:
        
        /**
         * Initializes the connection-pool.
         */
        void init();
        
        /**
         * Closes the connection-pool by stopping all threads.
         */
        void close();
        
        /** Container for the SMTP-connections. */
        vector< ThreadedSMTPConnection* > pool;
        
        /** Minimal pool-size. */
        unsigned long _minPoolSize;
        
        /** Maximal pool-size. */
        unsigned long _maxPoolSize;
        
        /** Status of pool-optimization. */
        bool _optimzePoolSize;
        
        /** Counter of all processed mails. */
        unsigned long _statsTotalMails;
        
        /** Counter of all mails with errors. */
        unsigned long _statsTotalErrors;
        
        /** Counter for pool-optimization. */
        unsigned long _statsMailsAfterOpt;
        
        /** Average number of tries to get an open connection. */
        double _avgNumOfTries;
        
        /** Root-Mean-Square of _avgNumOfTries. */
        double _rms;
        
        /** Hostname to send in HELO-commend. */
        string _myHostname;
        
        /** IP-address of SMTP-server. */
        string _smtpHost;
        
        /** Port of SMTP-server. */
        int _smtpPort;
        
        
    };
    
}

#endif  /* _SMTPCONNECTIONPOOL_H */

---