bleater

Documentation

Overview

Bleater: Something that goes baaa in the night.

Supports a a multi-tiered (parent with multiple children) bleat object which allows for a 'master level' control through the parent which affects all children, and individual control which affects only the child. See the test module for an example.

When the Baa() function is called, the message is written only if the indicaed level is <= the current level in the bleater, or <= than the parent level. When a parent's level is changed, it is "broadcast" to all children in an attempt to minimise the cycles needed to check for each bleat (the assumption is that the parent level rarely changes and pushing it is less expensive than constantly checking the parent object's value).

Each bleat message written is prefixed with the current unix timestamp, a human readable timestamp, the bleater prefix (if given), the level number in square brackets, and the formatted user message passed in printf() style on the Baa() call. The default human readable timestamp is of the form YYYY/MM/DD HH:MM:SSZ; use the Set_tsformat() function to supply a 'mask' if a different layout is desired. Masks are as described in the Golang time package. Bleat messages are automatically terminated with a newline, so including one in the message is not needed.

Index

• type Bleater
  • func Mk_bleater(level uint, target io.Writer) (b *Bleater)
  • func (b *Bleater) Add_child(cb *Bleater)
  • func (b *Bleater) Append_target(target_fname string, close_old bool) (err error)
  • func (b *Bleater) Baa(when uint, uformat string, va ...interface{})
  • func (b *Bleater) Baa_some(class string, freq int, when uint, uformat string, va ...interface{})
  • func (b *Bleater) Baa_some_reset(class string)
  • func (b *Bleater) Create_target(target_fname string, close_old bool) (err error)
  • func (b *Bleater) Dec_level()
  • func (b *Bleater) Get_level() uint
  • func (b *Bleater) Inc_level()
  • func (b *Bleater) Mk_logfile_nm(ldir *string, period int64) *string
  • func (b *Bleater) Set_level(l uint)
  • func (b *Bleater) Set_prefix(pfx string)
  • func (b *Bleater) Set_target(new_target io.Writer, close_old bool)
  • func (b *Bleater) Set_tsformat(fmt string)
  • func (b *Bleater) Sheep_herder(ldir *string, period int64)
  • func (b *Bleater) Would_baa(lvl uint) bool

Types

type Bleater

type Bleater struct {
	// contains filtered or unexported fields
}

func Mk_bleater

func Mk_bleater(level uint, target io.Writer) (b *Bleater)

Mk_bleater creates a new bleater object with a few initial settings.

func (*Bleater) Add_child

func (b *Bleater) Add_child(cb *Bleater)

Add_child allows a bleater object to be added to the given object as a child. Managing bleaters in a parent child organisation allows a 'master bleating volume' to be managed in the parent, while allowing the volume for a particular subsystem (child) to be set differently (louder) than the rest.

func (*Bleater) Append_target

func (b *Bleater) Append_target(target_fname string, close_old bool) (err error)

Append_target opens the target file and appends to it. If the file doesn't exist, it creates it. The new file is pushed down into all child bleaters if they exist.

func (*Bleater) Baa

func (b *Bleater) Baa(when uint, uformat string, va ...interface{})

Baa causes the message to be written to the output device if the current bleating level is greater or equal to the message level (when). If the when value is greater than the current level, the message is suppressed.

func (*Bleater) Baa_some

func (b *Bleater) Baa_some(class string, freq int, when uint, uformat string, va ...interface{})

Baa_some allows a caller to bleat messages belonging to a 'class' less often than every time called. The Baa_some function accepts additional parameters (class name, and frequency) and will bleat the message on the first call, and then every frequency of calls there after. Frequency is not saved with the class, so it is possible to change the frequency at any time.

The class counter is incremented only if the message would otherwise be written with respect to the value of when. Thus, a class poised to write a message on the next invocation will write that message as soon as the level is appropriate, and does not run the risk of always skipping if levels fluxuate.

func (*Bleater) Baa_some_reset

func (b *Bleater) Baa_some_reset(class string)

Baa_some_reset allows a bleat_some class to be reset such that the next bleat_some() will cause the message to be written and the counter cycled.

func (*Bleater) Create_target

func (b *Bleater) Create_target(target_fname string, close_old bool) (err error)

Create_target creates a new file and truncates it. All subsequent Baa() calls will write to this file. The newly created file will be 'pushed' down into all child bleaters.

func (*Bleater) Dec_level

func (b *Bleater) Dec_level()

Dec_level is a convenient way to decrease the volume by one.

func (*Bleater) Get_level

func (b *Bleater) Get_level() uint

Get_level returns the bleater's current level.

func (*Bleater) Inc_level

func (b *Bleater) Inc_level()

Inc_level is a convenient way to increase the volume by one.

func (*Bleater) Mk_logfile_nm

func (b *Bleater) Mk_logfile_nm(ldir *string, period int64) *string

Generate a new logfile name based on the current date, the log directory passed in and the cycle period.

The file name created will have the syntax:

<log_dir>/<prefix>.log.<date>

where <prefix> is taken from the bleater.

If period is >86400 seconds, then the file name is day based. If period is <86400 but > 3600 seconds, then file is based on hour, else the file includes the minute and is of the general form yyyymmddhhmm.

func (*Bleater) Set_level

func (b *Bleater) Set_level(l uint)

Set_level changes the volume for the object, and pushes it to any child bleaters.

func (*Bleater) Set_prefix

func (b *Bleater) Set_prefix(pfx string)

Set_prefix establishes the prefix for this bleater. The prefix is the portion of the message that is written after the timestamp.

func (*Bleater) Set_target

func (b *Bleater) Set_target(new_target io.Writer, close_old bool)

Set_target changes the output target and pushes the target to children. If close_old is set, the old target is closed (if possible), otherwise it is left alone. (it is not possible to close standard error, or any target that was not opened by al call to bleater.Create_target(). If new_target is nil, this just pushes the current target down.

func (*Bleater) Set_tsformat

func (b *Bleater) Set_tsformat(fmt string)

Set_tsformat allows the timestamp format that is written on a bleat message to be changed. Any format string that is supported by the Go time package may be used.

func (*Bleater) Sheep_herder

func (b *Bleater) Sheep_herder(ldir *string, period int64)

Go routine that manages the rolling over of the bleater log. We assume there is already a log open. Period defines when the log is rolled (e.g. 300 causes the log to be rolled on 5 minute boundaries, 3600 hour boundaries, and 86400 at midnight).

func (*Bleater) Would_baa

func (b *Bleater) Would_baa(lvl uint) bool

Would_baa will return true if the Baa method were invokde for the given level. This might be advantageous if the information that is to be bleated is fairly expensive to compute, and the application wishes to avoid the computation unless it is sure that it will be written.