/ 
Ubic-1.37_03
River stage two • 9 direct dependents • 15 total dependents
/ Ubic

NAME

Ubic - polymorphic service manager

VERSION

version 1.37_03

SYNOPSIS

Ubic->start("my-service");

Ubic->stop("my-service");

$status = Ubic->status("my-service");

DESCRIPTION

This module is a singleton OOP class.

All of its methods can be invoked as class methods or object methods.

INTRODUCTION

Ubic is a polymorphic service manager.

This module is a perl frontend to ubic services.

Further directions:

if you are looking for a general introduction to Ubic, see Ubic::Manual::Intro;

if you want to use ubic from command line, see ubic;

if you want to manage ubic services from perl scripts, read this POD;

if you want to write your own service, see Ubic::Service and other Ubic::Service::* modules.

CONSTRUCTOR

Ubic->new({ ... })

All methods in this package can be invoked as class methods, but sometimes you may need to override some status dirs. In this case you should construct your own Ubic instance.

Note that you can't create several instances in one process and have them work independently. So, this constructor is actually just a weird way to override service_dir and data_dir.

Constructor options (all of them are optional):

service_dir

Name of dir with service descriptions (which will be used to construct root Ubic::Multiservice::Dir object).

data_dir

Dir into which ubic stores all of its data (locks, status files, tmp files).

LSB METHODS

See LSB documentation for init-script method specifications.

Following functions are trying to conform, except that all dashes in method names are replaced with underscores.

Unlike Ubic::Service methods, these methods are guaranteed to return blessed versions of result, i.e. Ubic::Result::Class objects.

start($name)

Start service.

stop($name)

Stop service.

restart($name)

Restart service; start it if it's not running.

try_restart($name)

Restart service if it is enabled.

reload($name)

Reloads service if reloading is implemented; throw exception otherwise.

force_reload($name)

Reloads service if reloading is implemented, otherwise restarts it.

Does nothing if service is disabled.

status($name)

Get service status.

OTHER METHODS

enable($name)

Enable service.

Enabled service means that service *should* be running. It will be checked by status and marked as broken if it's enabled but not running.

is_enabled($name)

Returns true value if service is enabled, false otherwise.

disable($name)

Disable service.

Disabled service means that service is ignored by ubic. It's state will no longer be checked by watchdog, and pings will answer that service is not running, even if it's not true.

cached_status($name)

Get cached status of enabled service.

Unlike other methods, it can be invoked by any user.

do_custom_command($name, $command)

Execute custom command $command for given service.

service($name)

Get service object by name.

has_service($name)

Check whether service $name exists.

services()

Get list of all services.

service_names()

Get list of names of all services.

root_service()

Get root service.

Root service doesn't have a name and returns all top-level services with services() method. You can use it to traverse the whole service tree.

compl_services($line)

Return list of autocompletion variants for given service prefix.

set_cached_status($name, $status)

Write new status into service's status file.

get_data_dir()

Get data dir.

set_data_dir($dir)

Set data dir, creating it if necessary.

Data dir is a directory with service statuses and locks. (See Ubic::Settings for more details on how it's calculated).

This setting will be propagated into subprocesses using environment, so following code works:

Ubic->set_data_dir('tfiles/ubic');
Ubic->set_service_dir('etc/ubic/service');
system('ubic start some_service');
system('ubic stop some_service');
set_ubic_dir($dir)

Deprecated. This method got renamed to set_data_dir().

set_default_user($user)

Set default user for all services.

This is a simple proxy for Ubic::Settings->default_user($user).

get_service_dir()

Get ubic services dir.

set_service_dir($dir)

Set ubic services dir.

INTERNAL METHODS

You shouldn't call these from a code which doesn't belong to core Ubic distribution.

These methods can be changed or removed without further notice.

status_file($name)

Get status file name by service's name.

status_obj($name)

Get status persistent object by service's name.

It's a bad idea to call this from any other class than Ubic, but if you'll ever want to do this, at least don't forget to create Ubic::AccessGuard first.

status_obj_ro($name)

Get readonly, nonlocked status persistent object by service's name.

access_guard($name)

Get access guard (Ubic::AccessGuard object) for given service.

lock($name)

Acquire lock object for given service.

You can lock one object twice from the same process, but not from different processes.

do_sub($code)

Run any code and wrap result into Ubic::Result::Class object.

do_cmd($name, $cmd)

Run $cmd method from service $name and wrap any result or exception into Ubic::Result::Class object.

forked_call($callback)

Run $callback inside fork and return its return value.

Interaction happens through temporary file in $ubic-{tmp_dir}> dir.

CONTRIBUTORS

Andrei Mishchenko <druxa@yandex-team.ru>

Yury Zavarin <yury.zavarin@gmail.com>

Dmitry Yashin

Christian Walde <walde.christian@googlemail.com>

Ivan Bessarabov <ivan@bessarabov.ru>

SEE ALSO

Most Ubic-related links are collected on github wiki: http://github.com/berekuk/Ubic/wiki.

SUPPORT

Our mailing list is ubic-perl@googlegroups.com. Send an empty message to ubic-perl+subscribe@googlegroups.com to subscribe.

These is also an IRC channel: irc://irc.perl.org#ubic.

AUTHOR

Vyacheslav Matyukhin <mmcleric@yandex-team.ru>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Yandex LLC.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.