001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache license, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the license for the specific language governing permissions and
015 * limitations under the license.
016 */
017
018package org.apache.logging.log4j.core.async;
019
020import org.apache.logging.log4j.core.LogEvent;
021import org.apache.logging.log4j.core.jmx.RingBufferAdmin;
022
023/**
024 * Encapsulates the mechanism used to log asynchronously. There is one delegate per configuration, which is shared by
025 * all AsyncLoggerConfig objects in the configuration.
026 */
027public interface AsyncLoggerConfigDelegate {
028
029    /**
030     * If possible, delegates the invocation of {@code callAppenders} to the background thread and returns {@code true}.
031     * If this is not possible (if it detects that delegating to the background thread would cause deadlock because the
032     * current call to Logger.log() originated from the background thread and the ringbuffer is full) then this method
033     * does nothing and returns {@code false}. It is the responsibility of the caller to process the event when this
034     * method returns {@code false}.
035     * 
036     * @param event the event to delegate to the background thread
037     * @param asyncLoggerConfig the logger config to call from the background thread
038     * @return {@code true} if delegation was successful, {@code false} if the calling thread needs to process the event
039     *         itself
040     */
041    boolean tryCallAppendersInBackground(LogEvent event, AsyncLoggerConfig asyncLoggerConfig);
042
043    /**
044     * Creates and returns a new {@code RingBufferAdmin} that instruments the ringbuffer of this
045     * {@code AsyncLoggerConfig}.
046     * 
047     * @param contextName name of the {@code LoggerContext}
048     * @param loggerConfigName name of the logger config
049     * @return the RingBufferAdmin that instruments the ringbuffer
050     */
051    RingBufferAdmin createRingBufferAdmin(String contextName, String loggerConfigName);
052}