NAME
    Mail::Delivery::Queue - handle mail queue system.

SYNOPSIS
        use Mail::Message;
        $msg = new Mail::Message;

        use Mail::Delivery::Queue;
        my $queue = new Mail::Delivery::Queue { directory => "/some/where" };

        # queue in a new message
        # "/some/where/new/$queue_id" is created.
        $queue->in( $msg ) || croak("fail to queue in");

        # ok to deliver this message !
        $queue->setrunnable() || croak("fail to set queue deliverable");

DESCRIPTION
    "Mail::Delivery::Queue" provides basic manipulation of mail queue.

DIRECTORY STRUCTURE
    "new()" method assigns a new queue id $qid but not do actual works.

    "in()" method creates a new queue file $qf. So, $qf follows:

       $qf = "$queue_dir/new/$qid"

    When $qid queue is ready to be delivered, you must move the queue file
    from new/ to active/ by rename(2). To make this queue deliverable, use
    "setrunnable()" method.

       $queue_dir/new/$qid  --->  $queue_dir/active/$qid

    The actual delivery is done by other modules such as "Mail::Delivery".
    "Mail::Delivery::Queue" manipulates only queue around things.

METHODS
  new($args)
    constructor. You must specify at least "queue directory" as

        $args->{ dirctory } .

    If "id" is not specified, "new()" assigns the queue id, queue files to
    be used. "new()" assigns them but do no actual works.

INFORMATION
  id()
    same as get_queue_id(). return the queue id assigned to this object
    $self.

  set_queue_id($id)
    save the queue id.

  get_queue_id()
    return the queue id assigned to this object $self.

  getidinfo($id)
    return information related with the queue id $id. The returned
    information is

            id         => $id,
            path       => "$dir/active/$id",
            sender     => $sender,
            recipients => \@recipients,

  list( [ $class ] )
    return queue list as ARRAY REFERENCE. by default, return a list of queue
    filenames in "active/" directory.

        $ra = $queue->list();
        for $qid (@$ra) {
            something for $qid ...
         }

    where $qid is like this: 990157187.20792.1

  list_all()
    return all queue list in all classes.

  set_policy($policy)
    set queue management policy.

  get_policy()
    return queue management policy.

SCHEDULE MANAGEMENT
  update_schedule($id)
    update scheduling for this queue (id = $id).

  reschedule()
    reschedule queues. wake up queue if needed.

LOCK
  lock()
  unlock()
IO
  open($class, $args)
    open incoming queue of this queue id with mode $mode and return the file
    handle.

  close($class)
    close.

  in($msg)
    "in()" creates a queue file in "new/" directory ("queue_directory/new/".

    $msg is "Mail::Message" object by default. If $msg object has print()
    method, arbitrary $msg is acceptable.

    REMEMBER YOU MUST DO "setrunnable()" for the queue to be delivered. If
    you not "setrunnable()" it, the queue file is removed by "DESTRUCTOR".

  add ($msg)
    same as in().

  delete()
    remove all files assigned to this queue $self.

  remove()
    same as delete().

  valid()
    check if the queue file is broken or not. return 1 (valid) or 0
    (broken).

  setrunnable()
    set the status of the queue assigned to this object $self deliverable.
    This queue is scheduled to be delivered.

    In fact, setrunnable() "rename"s the queue id file from "new/" directory
    to "active/" directory like "postfix" queue strategy.

  touch($file)
ACCESS METHOD
  set($key, $args)
    defined for compatibility.

       $queue->set('sender', $sender);
       $queue->set('recipients', [ $recipient0, $recipient1 ] );

    It sets up delivery information in "info/sender/" and "info/recipients/"
    directories.

UTILITIES
  is_valid_active_queue()
    check if this object (queue) is sane as active queue?

  is_valid_queue()
    check if this object (queue) is sane as active queue?

  dup_content($old_class, $new_class)
    duplicate $old_class content at a class $new_class.

DIR/FILE UTILITIES
LOGGING INTERFACE
CLEAN UP GARBAGES
  expire($class)
    remove too old queue files in the specified queue. expire all queue if
    $class unspecified.

  cleanup()
    remove too old incoming queue files.

DEBUG
CODING STYLE
    See "http://www.fml.org/software/FNF/" on fml coding style guide.

AUTHOR
    Ken'ichi Fukamachi

COPYRIGHT
    Copyright (C) 2001,2002,2003,2004,2005,2006,2008 Ken'ichi Fukamachi

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

HISTORY
    Mail::Delivery::Queue first appeared in fml8 mailing list driver
    package. See "http://www.fml.org/" for more details.

