SYNOPSIS

    use Basicos::Spool;
    
    my $spool = Basicos::Spool->new( 'myworks', '/var/spool/myprogram' );

    my $seq = $spool->queue( 'hola a todo el mundo' );
    
=head1 DESCRIPTION

Este módulo se encarga de gestionar colas (spools) en disco y que pueden utilizarse para muchos fines.

Para crear una cola sólo es necesario proporcionarle el nombre de la misma y el directorio raíz donde se alojan todas. La ruta física de la cola no es más que la concatenación de estos dos valores.

Cada cola incluye un archivo de nombre .SEQ y que permite controlar que los nombres de los archivos sean únicos, y otro llamado .LCK para permitir accesos concurrentes (mediante perl/flock).

__top

SUBRUTINES/METHODS

new( )

    my $spool = Basicos::Spool->new( $name, $path );

Este método crea un objeto para controlar una cola inicializando la misma si no existe.

Los parámetros (obligatorios) son los siguientes:

Nombre Nombre que tiene la cola de impresión como directorio dentro de la raíz.
Ruta Directorio raíz de las colas

Retorna un objeto Basicos::Spool si todo funciona.

seq( )

    my $numero = $spool->seq();

Obtiene un número de secuencia único para la cola y actualiza el valor del contador, por lo que cada llamada efectúa varias operaciones en la misma.

Nota: este método no está diseñado para ser llamado por programas de aplicación, sino por módulos que derivan de éste.

queue( $data )

    my $data = Freeze( \%my_hash );

    my $seq = $spool->queue( $data );

Encola un elemento guardando el valor pasado en un archivo, cuyo nombre se forma del número de secuencia activo y la extensión .data.

Este método está pensado para ser sobrecargado por clases derivadas de manera que puedan almacenarse otros tipos datos, así como varios archivos con el mismo número de entrada.

Los parámetros (obligatorios) que recibe son:

Variable escalar con el contenido a almacenar en el elemento de la cola.

Retorna el número de secuencia asignada al nuevo elemento, que conviene guardar si posteriormente se desea borrar ó actualizar el elemento en la cola.

__top

DIAGNOSTICS

El módulo efectúa llamadas a croak() ante los siguientes escenarios:

Fallo de escritura en el directorio raíz ó en el directorio particular de la cola.
Fallo en la creación de archivos en el directorio de la cola (cuando va a encolar un elemento)

__top

DEPENDENCIES

the Basicos::Base manpage: Clase base para automatizar la creación de objetos
the File::Path manpage: Funciones para crear directorios incluyendo los padres.

__top

BUGS AND LIMITATIONS

There are no known bugs in this module.

Please report problems to ``Victor Moral'' victor@taquiones.net or ``Angel Ortega'' <angel@triptico.com>.

Patches are welcome.

__top

AUTHOR

Víctor Moral <victor@taquiones.net>, Angel Ortega <angel@triptico.com>

__top

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program 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.

__top

Basicos::Spool